descr='[trademarkserif]' Programming GuideDocument Number 007-1633-040CONTRIBUTORSWritten by David GravesUpdated by Don MocciaEdited by Nancy Schweiger and Christina CaryCover design and illustration by Rob Aguilar, Rikk Carey, Dean Hodgkinson, Erik Lindholm, and Kay MaitzProduction by Heather HermstadEngineering contributions by Roger Chickering, Ken Kershner, Baron Roberts, David Story, and Craig UpsonEngineering Update by Ray Niblettname='copyrightserif' font=symbol charset=fontspecific code=211
descr='[mdash]' All Rights ReservedThe contents of this document may not be copied or duplicated in any form, in whole or in part, without the prior written permission of Silicon Graphics, Inc.RESTRICTED RIGHTS LEGENDUse, duplication, or disclosure of the technical data contained in this document by the Government is subject to restrictions as set forth in subdivision (c) (1) (ii) of the Rights in Technical Data and Computer Software clause at DFARS 52.227-7013 and/or in similar or successor clauses in the FAR, or in the DOD or NASA FAR Supplement. Unpublished rights reserved under the Copyright Laws of the United States. Contractor/manufacturer is Silicon Graphics, Inc., 2011 N. Shoreline Blvd., Mountain View, CA 94039-7311.Silicon Graphics and IRIS are registered trademarks and Impressario, IRIX, Personal IRIS, Indigo Magic, and WorkSpace are trademarks of Silicon Graphics, Inc. Adobe Photoshop, PostScript, and TranScript are trademarks of Adobe Systems, Inc., which may be registered in certain jurisdictions. TIFF is a trademark of Aldus Corporation. Apple, Macintosh, and LaserWriter are registered trademarks of Apple Computer, Inc. AT&T System V is a registered trademark and Documenter's Workbench is a trademark of AT&T. BSD is a trademark of Berkeley Software Distribution. ColorSynergy is a registered trademark of Candela. Canon is a trademark of Canon U.S.A., Inc. Centronics is a registered trademark of Centronics Data Computer Corporation. GIF and Graphics Interchange Format are trademarks of CompuServe Incorporated. Color Stylus, Stylus, and Stylus Pro are trademarks of Epson America, Inc. Primera is a registered trademark of Fargo Electronics, Inc. Genicom is a trademark of Genicom Corporation. FLEXlm is a trademark of GLOBEtrotter Software, Inc. Hewlett Packard, HP, LaserJet, DesignJet, HP-GL, DeskJet, ScanJet, and PaintJet are registered trademarks, and CopyJet and JetDirect are trademarks of Hewlett-Packard Company. PhotoCD is a trademark of Eastman Kodak Company. Lexmark and Optra are registered trademarks of Lexmark International, Inc. Colortron is a trademark of Light Source Computer Images. X Window System is a trademark of the Massachusetts Institute of Technology. Motorola is a registered trademark of Motorola, Inc. OSF, Motif, Motif widget, and OSF/Motif are trademarks of Open Software Foundation. ColorPoint and ColorPoint 2 are trademarks of Seiko Epson Corporation. Tektronix and Phaser are registered trademarks of Tektronix, Inc. UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company, Ltd. Versatec is a registered trademark of Versatec Corporation.ID="43783"About This GuideImpressarioname='trade' font=symbol charset=fontspecific code=228
descr='[trade]' is a printing and scanning environment for Silicon Graphics« IRIS« workstations. The Developer's Kit, included with Impressario, provides solutions for a wide range of UNIX« audiences: printer driver and scanner driver developers, application program developers, and end users.The goal of Impressario is to provide an intuitive, friendly, and reliable interface for end users, while increasing system capability and performance for driver and application developers. Users can simply drag and drop a file onto a printer icon to print the file. Other graphical tools in the end user's environment provide information on the capabilities and status of any accessible printer or scanner.The Impressario printing environment provides two main end-user enhancements:support for a wide range of printers, from high-quality color printers to high-speed black-and-white printersgraphical printing tools that allow a user to submit a print job and monitor the status of the job and the printerImpressario enables developers of printer drivers and scanner drivers to showcase each product's special features and capabilities and present them to the user via a graphical dialog box. Application programmers can greatly reduce the development time required to support printing and scanning functions.TipThe Impressario release notes contain the most recent information about the product. They are provided online and can be read using ID="intro1"relnotes or grelnotesID="intro2"ID="intro3". In addition, the directory /usr/impressario contains information of interest to both application developers and end users.The Impressario ID="intro4"printing environment is built on top of the AT&T System VID="intro5"«, Release 3 (SVR3) printer spooling interface. Model files, filters, and printer drivers are provided to convert a wide variety of file types (ISO text files, Silicon Graphics image files, PostScriptID="intro6"ID="intro7"ID="intro8"name='trade' font=symbol charset=fontspecific code=228
descr='[trade]'files, and so forth) to formats for both raster printers and PostScript printers. Using the Impressario host-based PostScript interpreter, it is possible to print PostScript documents to raster printers with performance that greatly surpasses printer-based PostScript interpreters. Impressario also includes the PrintBox Motif widgetID="intro9"name='trade' font=symbol charset=fontspecific code=228
descr='[trade]', a graphical user interface (GUI) for printing.ID="intro10"ID="intro11"Impressario ID="intro12"server software contains filters and drivers for sending jobs from a host workstation to a printer. In addition, all Impressario printer drivers maintain status information in a globally available printer object database (POD).The Impressario ID="intro13"scanning environment provides generic scanner support. Impressario scanner application programs and Impressario scanner drivers run as separate executables, enabling any scanning application to interact with all scanner drivers.Impressario gives application developers a number of valuable resources, includinglibspoolID="intro14"ID="intro15", a printer spooling system abstraction library that enables complex printing functions to be defined with only a few lines of codeapplication programming interfaces for easy access to the end user's scanning environmenta network-transparent version of the printer object database library routines to inquire directly about printer configuration and statusLBL="" HELPID=""AudienceID="intro16"The Impressario Programming Guide is written for the following users:printer driver developersscanner driver developersapplication program developers who need to print or scan from their applicationsLBL="" HELPID=""New FeaturesThe 2.0 release of Impressario contains these new features:ID="intro17"An Adobe Level II Configurable PostScript Interpreter (CPSI)The CPSI supports banded devices, such as inkjet plotters and inkjet printers, reducing the amount of host memory needed to use them.A Generic Color PostScript driverThis driver converts files to be printed into PostScript, which it sends to printers with PostScript interpreters, including selected color printers.A new filter, text2ps, that converts ASCII text to PostScriptAll Impressario drivers now use text2ps to convert ASCII text files.The Developer's KitIt is bundled with Impressario and is no longer a separate option.Impressario 2.0 also adds support for the following:Hewlett-Packard DesignJetID="intro18"« 750C plottersHewlett-Packard DeskJetID="intro19"« 660C, 850C, 855C, and 1600C color inkjet printersID="intro20"ID="intro21"ID="intro22"Hewlett-Packard LaserJetID="intro23"« 4V, 4 Plus, 4Si, 5L, 5P, and 5Si printersID="intro24"ID="intro25"ID="intro26"ID="intro27"ID="intro28"Hewlett-Packard JetDirectname='trade' font=symbol charset=fontspecific code=228
descr='[trade]' network adaptors for various printersLexmark Optra« R, Rx, L, Lx, and Lxi monochrome laser printersEpson Color Stylusname='trade' font=symbol charset=fontspecific code=228
descr='[trade]', and Stylus Pro XL printersInternational Color Consortium (ICC) color profiles for the color management of image files, such as GIFname='trade' font=symbol charset=fontspecific code=228
descr='[trade]' and TIFFname='trade' font=symbol charset=fontspecific code=228
descr='[trade]'NoteThe release notes list all supported printers and scanners, and have details about the JetDirect network adaptors.LBL="" HELPID=""How to Use This GuideID="intro29"Since this guide has four separate audiences, the list provided below gives the areas of most interest to each user:Printer driver developers should read chapters 1¡6, 10, 11, and 12.Printer application program developers should read chapters 1, 6, and 12.Scanner driver developers should read chapters 1, 2, 7¡9, 11, and 12.Scanner application program developers should read chapters 1, 2, 9, and 12.LBL="" HELPID=""Conventions Used in This GuideID="intro30"ID="intro31"ID="intro32"The followings conventions are intended to help make information easy to access and understand:italicID="intro33"ID="intro34"Used for arguments in a command line that you replace with a valid value. In text it indicates an argument, button, command, document title, file name, glossary item, new term, or variable. For example:Use the phandler command to ....The NAME variable identifies the printer name.ALL CAPSUsed for defined constants in text. For example:The SC_PROGFEED bit should be set.ID="intro35"boldID="intro36"Denotes command-line options, keywords, and functions. For example:The -o option directs output.SCErrorString() returns a text string.CourierID="intro37"ID="intro38"Used for code examples and screen displays. For instance, the following is a code example:int
AdvanceFeeder(SCANINFO *scan)
{
drverr = SCENOFEEDER;
return -1;
}ID="intro39"Courier boldID="intro40"Used for user input. For example:vstiff /usr/tmp/sample.blastfile<Enter>< >Used to enclose arguments, parameters, and nonprinting keys (see above).[ ]Enclose optional command arguments. Do not enter the brackets. Example:ID="intro41"[optional_entry]LBL="" HELPID=""Document OverviewID="intro42"IDREF="58588" TYPE="TITLE"Chapter 1, "Impressario Architecture," discusses the Impressario printing and scanning architectures and defines Impressario compliance for printer driver and scanner driver developers.IDREF="91816" TYPE="TITLE"Chapter 2, "Installing Impressario Software," explains how to install the Impressario software. It includes product-specific information that is supplemental to the IDREF="29804" BOOK="IA_InstLicns" FILE="" HDG="29804" INFO=""IRIX Admin: Software Installation and Licensing
manual and the IDREF="96534" BOOK="PerSysAdmin" FILE="" HDG="96534" INFO=""Personal System Administration Guide
.IDREF="26455" TYPE="TITLE"Chapter 3, "Printer Drivers," provides an overview of printer driver processing, plus a detailed analysis and discussion of an example printer driver. The required printer filter/driver options are also covered.IDREF="35103" TYPE="TITLE"Chapter 4, "Printer Model Files," discusses the printer model files and describes the modifications to be made by printer driver developers to the printer model file template.IDREF="20688" TYPE="TITLE"Chapter 5, "Printer Graphical Options Panel," discusses the graphical options panel that visually showcases a printer's features. The major topics discussed are options handling, panel layout, development, naming, installation, invocation, and termination.IDREF="20198" TYPE="TITLE"Chapter 6, "Printing Libraries," describes the libraries used by printer drivers, filters, and applications. The libraries described are the libspool library, the libprintui library, and the libpod library.IDREF="64426" TYPE="TITLE"Chapter 7, "Scanner Drivers," explains how to write a scanner driver. It provides a detailed analysis of the template scanner driver. The major topics are the driver template, header files, data structures, functions, installation, and testing.IDREF="87965" TYPE="TITLE"Chapter 8, "Scanner-Specific Options," discusses how to implement scanner-specific options for a scanner driver. The major topics are the options program, perspectives, and installation and testing.IDREF="59965" TYPE="TITLE"Chapter 9, "Generic Scanner Interface," describes a generic interface between a scanner driver and an application program. The major topics are the coordinate system for scanning, data structures, and data type conventions.IDREF="11368" TYPE="TITLE"Chapter 10, "Testing for Impressario Compatibility," explains how to use the programs that test printing compatibility with the Impressario environment. It explains how to test Impressario printing compatibility, an Impressario printer, and an Impressario printer software installation.IDREF="78690" TYPE="TITLE"Chapter 11, "Packaging Your Impressario Product," explains how to package the Impressario software product that you have created.IDREF="94618" TYPE="TITLE"Chapter 12, "Enhancing Impressario With Plug-Ins," explains how to add new features to the Impressario open architecture. The major topics are how the Impressario file conversion pipeline works, how to add a new filetype to Impressario, and how to use an alternate PostScript RIP.IDREF="68392" TYPE="TITLE"Appendix A, "Stream TIFF Data Format," describes the Stream TIFF file format, the primary interchange file format between printer filters and drivers; and libstiff, a C application program interface (API) used to read and write Stream TIFF files. Stream TIFF is also used by gscan to store images in TIFF files and to scan to the screen (in conjunction with vstiff).IDREF="79172" TYPE="TITLE"Appendix B, "Silicon Graphics Image File Format API," describes libimp, the C-language API for reading and writing Silicon Graphics Image format files. The image processing features of libimp are also described.IDREF="64689" TYPE="TITLE"Appendix C, "Printer Object Database (POD) File Formats," defines the file formats for printer configuration, status, and log files in the POD. The major topics are general syntax, input parsing rules for libpod files, printer configuration file format, and printer status file format.IDREF="34235" TYPE="TITLE"Appendix D, "Transition Notes," explains how to migrate from Impressario 1.2 software to Impressario 2.0. It also explains how Impressario application developers and filter/driver developers can take advantage of the new features in Impressario 2.0.IDREF="36071" TYPE="TITLE"Appendix E, "Scanner Driver Architecture," describes the architecture of a scanner driver and discusses the template scanner driver, required and optional functions, and queues and multi-threaded scanner drivers.IDREF="14153" TYPE="TITLE"Appendix F, "Reference Pages," lists all Impressario online reference pages: general interest, printer developers, and scanner developers.IDREF="67009" TYPE="TITLE"Appendix G, "Color Management In Impressario," discusses using ICC color profiles and PostScript Color Rendering Dictionaries to promote color consistency among devices such as monitors, scanners, and printers.IDREF="38738" TYPE="TITLE"Appendix H, "Using the Adobe Configurable PostScript Interpreter," discusses legal restrictions on developers who use software licensed by Silicon Graphics from Adobe Systems.LBL="" HELPID=""ID="45666"Related PublicationsID="intro43"LBL="" HELPID=""Online BooksID="intro44"ID="intro45"The following books, available online through Silicon Graphics, contain information related to Impressario:Programming on Silicon Graphics Systems: An Overview, Silicon Graphics, Inc.Indigo Magic Desktop Integration Guide, Silicon Graphics, Inc.IRIX Device Driver Programming Guide, Silicon Graphics, Inc.IRIX Device Driver Reference Pages, Silicon Graphics, Inc.IRIX Admin: Peripheral Devices, Silicon Graphics, Inc.Volume One: Xlib Programming Manual, O'Reilly & AssociatesVolume Four: X Toolkit Intrinsics Programming Manual, O'Reilly & AssociatesOSF/Motif Programmer's Guide, Prentice-Hall, Inc.OSF/Motif Programmer's Reference, Prentice-Hall, Inc.OSF/Motif Style Guide, Prentice-Hall, Inc.Impressario User's Guide, Silicon Graphics, Inc.LBL="" HELPID=""Online Release NotesAfter installing online documentation, you can view the Impressario release notes. If you have a graphics system, select "Release Notes" from the Help Toolchest to display the grelnotes graphical browser. Refer to the grelnotes(1) reference page for information on options to this command. If you do not have a graphics system, you can use the relnotes command. Refer to the relnotes(1) reference page for accessing the online release notes.Adding the product name to the relnotes command displays the table of contents for that product's release notes. For example:% relnotes Impressario The chapters for the "Impressario" product's release notes are: chap title 1 Introduction 2 Installation Information 3 Changes and Additions 4 Bug Fixes 5 Known Problems and Workarounds 6 Documentation Errors Use "/usr/sbin/relnotes productname chapter" to view a chapterLBL="" HELPID=""Online Reference PagesID="intro46"ID="intro47"IDREF="14153" TYPE="TITLE"Appendix F lists the reference pages provided online with Impressario. To access them, enter:man page-nameLBL="" HELPID=""Release Identification InformationThe Impressario release identification information is listed below:Version number: 2.0Product code Impressario Server: SC4-IMPS-2.0 CDSystem software requirements: IRIX 6.2 or laterNoteThe Developer's Kit is bundled with Impressario and is no longer a separate option. The Impressario Programming Guide is available only as an online book.LBL="1"ID="58588"Impressario ArchitectureID="chap11"This chapter discusses the Impressario printing and scanning architectures and defines Impressario compliance for printer driver and scanner driver developers. By complying with Impressario guidelines, you make your job easier, you ensure a consistent end-user experience, and you greatly improve the chances of effortless transitions to future releases of Impressario.The following topics are discussed in this chapter:IDREF="92817" TYPE="TITLE""Impressario Printing Architecture"IDREF="33402" TYPE="TITLE""Compliance for Printer-Driver Developers"IDREF="40351" TYPE="TITLE""Printing Application Programming Interfaces"IDREF="98401" TYPE="TITLE""Printing Application Development"IDREF="40794" TYPE="TITLE""Complying With the Impressario Scanning Architecture"IDREF="69665" TYPE="TITLE""Developing a Scanner Driver"IDREF="64037" TYPE="TITLE""Developing a Scanner Application"LBL="" HELPID=""OverviewID="chap12"Impressario allows files of different types to be printed on any installed printer and images to be scanned from a scanner, a workstation monitor, or a Silicon Graphics Image file. A visual end-user environment makes it easy for users to add new devices and for applications to take advantage of those devices by providing graphical interfaces for these purposes:installing printers (see the ID="chap13"printers(1M) reference page)ID="chap14"modifying printer settings (see PrintPanel [glp(1)] or ID="chap15"printersID="chap16")checking printer status (see PrintStatus(1))ID="chap17"ID="chap18"submitting print jobs from applications (see the PrintBox widget)ID="chap19"ID="chap110"installing scanners (see scanners(1M))ID="chap111"using scanners (see gscan(1))To maintain a consistent, reliable, and easy-to-use environment, Impressario provides the following libraries for application developers:libspoolID="chap112"ID="chap113"a C application program interface (API) to the UNIX printer spooling systemlibprintuiID="chap114"ID="chap115"ID="chap116"a C graphical user interface (GUI) library for printing that is compatible with MotiflibpodID="chap117"ID="chap118"ID="chap119"a C-language API to the Printer Object Database (POD)ID="chap120"libscanID="chap121"ID="chap122"ID="chap123"a C-language API to the Impressario scanning systemlibstiffID="chap124"ID="chap125"ID="chap126"a C-language API for reading and writing Stream TIFF (STIFF) fileslibimpID="chap127"ID="chap128"ID="chap129"a C-language API for reading and writing Silicon Graphics Image filesThe following final, crucial elements must be provided by driver developers:For printers: a compliant printer driver that reports printer status through ID="chap130"libpod and, optionally, a graphical options panelFor scanners: a scanner driver for the driver side of the generic scanner interface and, optionally, a scanner-specific options panelLBL="" HELPID=""ID="92817"Impressario Printing ArchitectureID="chap131"ID="chap132"ID="chap133"This section describes the steps that developers of printer drivers and printing applications must take to comply with Impressario specifications.IDREF="55556" TYPE="GRAPHIC"Figure 1-1 is an overview of Impressario printing components. A more detailed version of this diagram is available online in /usr/impressario/doc.FILE="chap1-8.gif" POSITION="INLINE" SCALE="FALSE"LBL="1-1"Figure 1-1 ID="55556"Impressario Printing ArchitectureThe following sections detail the steps that should be followed to achieve Impressario compliance for printer drivers and printing applications.LBL="" HELPID=""ID="33402"Compliance for Printer-Driver DevelopersID="chap134"The steps shown in IDREF="83334" TYPE="GRAPHIC"Figure 1-2 (discussed below) show how to develop and integrate a printer driver for Impressario.FILE="fig1-2.gif" POSITION="INLINE" SCALE="FALSE"LBL="1-2"Figure 1-2 ID="83334"Printer Driver Development FlowchartLBL="" HELPID=""Step 1: Develop Printer Driver (Required)ID="chap135"Your printer driver must comply with the Impressario Filter/Driver Specification (see IDREF="77047" TYPE="TITLE""The Filter/Driver Specification and psrip" in Chapter 3) so that a model file that is Impressario compliant can execute the driver correctly. This specification describes standard driver behavior and the command-line arguments that must be processed. See /usr/impressario/src/drivers and IDREF="26455" TYPE="TITLE"Chapter 3 for the source code and an example driver. The driver must update the POD files through calls to "local" functions of the library ID="chap136"libpod. (See IDREF="20198" TYPE="TITLE"Chapter 6, "Printing Libraries.") The formats of the POD files are described in IDREF="64689" TYPE="TITLE"Appendix C, "Printer Object Database (POD) File Formats."LBL="" HELPID=""Step 2: Provide POD Files (Required)ID="chap137"A set of POD files consists of a configuration file, a printer log file, and a printer status file. Each POD file has the same base name as the printer model file. The extensions on these files are: ID="chap138"ID="chap139"ID="chap140"ID="chap141"ID="chap142".config, .log, and ID="chap143"ID="chap144".status, respectively. To create these files, start with the example set of POD files in the directory ID="chap145"/usr/impressario/src/data. The POD files you create must be installed in the directory /usr/lib/print/data when you install your software. See IDREF="78690" TYPE="TITLE"Chapter 11, "Packaging Your Impressario Product," for more information.LBL="" HELPID=""Step 3: Create Model File (Required)ID="chap146"Your model file must conform to the Impressario model file specification. This is done by starting with the template model file provided with Impressario and adding your developer-specific processing. Model files must be installed in ID="chap147"/var/spool/lp/model. Follow the Impressario model file template to create a model file that properly updates the desktop printer status icon and interacts properly with Impressario subsystems. (See IDREF="35103" TYPE="TITLE"Chapter 4, "Printer Model Files," for more information on model files.)LBL="" HELPID=""Step 4: Provide Data Filters (As Needed)ID="chap148"Filters must conform to the filter/driver specification. (See IDREF="77047" TYPE="TITLE""The Filter/Driver Specification and psrip" in Chapter 3 for more information.) Filter programs must be installed in ID="chap149"/usr/lib/print. It is recommended that any data filtering be performed directly by the driver. (Filters are programs that change the format of a data file; drivers communicate bidirectionally with the printer.) See chapter 12 for step-by-step instructions on adding new file conversion filters.LBL="" HELPID=""Step 5: Create Graphical Options Panel (Recommended)ID="chap150"This step is optional, but it is strongly recommended that you showcase the features of your printer by providing a graphical options panel program. (See IDREF="20688" TYPE="TITLE"Chapter 5, "Printer Graphical Options Panel," for details.)LBL="" HELPID=""Step 6: Package Software for Distribution (Required)Package your Impressario software product for distribution. See IDREF="78690" TYPE="TITLE"Chapter 11 for detailed information.LBL="" HELPID=""Step 7: Verify Product on Server (Required)Check that your product media will install the printer support files you have developed on an Impressario server. Run the Impressario test programs testipr and testiconfig to assist in verifying the installation. (See ID="chap151"ID="chap152"IDREF="11368" TYPE="TITLE"Chapter 10 for detailed information.)LBL="" HELPID=""ID="40351"Printing Application Programming InterfacesID="chap153"ID="chap154"ID="chap155"To print a document on UNIX systems, you must submit a print job to one of the available spooling systems: the BSD spooling system (ID="chap156"lpr command) or the System V spooling system (ID="chap157"lp command). The System V spooling system is the default spooling system on all Silicon Graphics workstations. ID="chap158"ID="chap159"IDREF="91265" TYPE="GRAPHIC"Figure 1-3 shows the general Impressario spooling architecture for the lp spooler. Note that only one of the two paths shown below (PostScript printer or raster printer) would apply. That is, the output is either to a PostScript printer or a raster printer, not both.FILE="chap1-1.gif" POSITION="INLINE" SCALE="FALSE"LBL="1-3"Figure 1-3 ID="91265"General Filter/Driver ArchitectureID="chap160"Before Impressario, a true application program interface to the BSDname='trade' font=symbol charset=fontspecific code=228
descr='[trade]' and System V spooling systems was not available. Programmers had to create their own application programming interface or execute the lp or lpr command from their application.ID="chap161"ID="chap162"Impressario provides the application program interfaces listed in IDREF="42844" TYPE="TABLE"Table 1-1 below.COLUMNS="3"LBL="1-1"Table 1-1 ID="42844"Printing Application Programming InterfacesID="chap163"ID="chap164"ID="chap165"LEFT="0" WIDTH="44"APILEFT="50" WIDTH="64"Interfaces toLEFT="120" WIDTH="250"FunctionLEFT="0" WIDTH="44"libspoolLEFT="50" WIDTH="64"System V, BSDLEFT="120" WIDTH="250"Allows submission of a file or buffer to a printerLEFT="0" WIDTH="44"libprintuiLEFT="50" WIDTH="64"System V onlyLEFT="120" WIDTH="250"Provides Motif PrintBox widget for printing from applicationLEFT="0" WIDTH="44"libpodLEFT="50" WIDTH="64"System V, BSDLEFT="120" WIDTH="250"Gets status information on the printers currently availableLBL="" HELPID=""libspool APIID="chap166"ID="chap167"In its simplest form, ID="chap168"libspool allows you to submit a file or buffer to a printer. It also gives you control of spooling system options and printer-specific options.LBL="" HELPID=""libprintui APIID="chap169"ID="chap170"The API ID="chap171"libprintui is built on top of libspool. The ID="chap172"libprintui library contains a widget, compatible with Motif, that you can incorporate directly into your application. If your Motif application needs printing capabilities, libprintui will provide you with all of the basic functionality for submitting a print job as well as access to setting and saving printer-specific options. As mentioned earlier, libprintui interfaces only with the System V spooling system.LBL="" HELPID=""libpod APIID="chap173"ID="chap174"The ID="chap175"libpod library is built on top of libspool and an ancillary system daemon, poddID="chap176". The libpod library allows you to obtain detailed information about the capabilities of the printers currently available on the system. You can also get detailed status information about the printers. Most applications do not need to use libpod; however, for those that do, libpod provides a very powerful, network-transparent interface.IDREF="97764" TYPE="GRAPHIC"Figure 1-4 shows the relationship between an application program, the Impressario APIs, and the System V spooling system.FILE="chap1-5.gif" POSITION="INLINE" SCALE="FALSE"LBL="1-4"Figure 1-4 ID="97764"System V Spooling System InterfaceIDREF="50310" TYPE="GRAPHIC"Figure 1-5 shows the relationship between an application program, the Impressario ID="chap177"libspool API, and the BSD spooling system.FILE="chap1-7.gif" POSITION="INLINE" SCALE="FALSE"LBL="1-5"Figure 1-5 ID="50310"BSD Spooling System InterfaceLBL="" HELPID=""glp (PrintPanel)ID="chap178"ID="chap179"The "print" subsystem available with the IRIX operating system contains the program glp, a graphical standalone print job submittal tool. While not a true API, glp can be used by your application to submit print jobs. It is a standalone wrapper around the PrintBoxID="chap180" Motif widget in ID="chap181"libprintui.LBL="" HELPID=""ID="98401"Printing Application DevelopmentID="chap182"ID="chap183"The following Impressario application printing solutions are available:Perform non-graphical print functions via libspool.ID="chap184"Use ID="chap185"libspool, the spooling system abstraction library, for all non-graphical interaction with the BSD or System V spooling system. The libspool library functions perform a large amount of work to ensure successful spooling system interaction, work that a developer may not wish to reproduce.Perform graphical print functions via libprintuiID="chap186".Use the PrintBox Motif widget provided by the libprintui library for graphical print job submittal. The widget provides a consistent job submission dialog across all applications and greatly reduces the amount of development effort required. If you use this library, you don't need to use ID="chap187"libspool directly. ID="chap188"libprintui encapsulates those calls.Obtain printer status via libpodID="chap189" (optional).Use libpod library calls to get printer status, configuration, and log information. Status queries must be made through libpod calls; attempts to obtain this information through other means have unpredictable results. In most cases, application developers should use the "standard" forms of the libpod functions (the "local" forms of the functions are for use by printer driver developers and are not network-transparent).Submit graphical print jobs via glpID="chap190".If you are not using Motif, you may use glp to submit graphical print jobs from your application. If you use this method, you should have the print software package (shipped with IRIX 5.2 and later) as a prerequisite. While this method works, it is not recommended, as it is likely to be less efficient than using libprintui.LBL="" HELPID=""ID="40794"Complying With the Impressario Scanning ArchitectureID="chap191"This section describes how to comply with the Impressario specifications for scanner driver developers and scanner application developers.IDREF="76313" TYPE="GRAPHIC"Figure 1-6 illustrates the run-time components of the Impressario scanner architecture. Note that scanner applications, scanner-specific options programs, and scanner drivers all link with ID="chap192"libscan.a, which has separate modules for scanner applications and for scanner drivers.FILE="chap1-2.gif" POSITION="INLINE" SCALE="FALSE"LBL="1-6"Figure 1-6 ID="76313"Scanner Run-Time ComponentsThe main and scanner-specific modules of a scanner driver both register callback functions with ID="chap193"libscan.IDREF="38238" TYPE="GRAPHIC"Figure 1-7 shows the interprocess communication of the Impressario scanner architecture.FILE="chap1-3.gif" POSITION="INLINE" SCALE="FALSE"LBL="1-7"Figure 1-7 ID="38238"Interprocess Scanner CommunicationThe following sections describe how to achieve Impressario compliance for scanner drivers and applications.LBL="" HELPID=""ID="69665"Developing a Scanner DriverFollow these steps to develop and integrate a scanner driver that complies with Impressario:Develop the scanner driver. See IDREF="64426" TYPE="TITLE"Chapter 7, "Scanner Drivers," and IDREF="87965" TYPE="TITLE"Chapter 8, "Scanner-Specific Options," for detailed instructions.Create a graphical options panel. This step is optional, but it is recommended that you showcase the features of your scanner through this mechanism. See IDREF="87965" TYPE="TITLE"Chapter 8, "Scanner-Specific Options," for detailed instructions.Create distribution media that will install the driver on an Impressario server. Be sure to check that the media will install the scanner support files you have developed on an Impressario server. See IDREF="78690" TYPE="TITLE"Chapter 11 for detailed information.LBL="" HELPID=""ID="64037"Developing a Scanner ApplicationThere are two ways for an application to interact with the scanning system: Through libscan. This scanning system abstraction library provides a C-language API for scanners. Application programs can use libscan to retrieve data from any scanning device for which a driver exists. See the libscan(3) reference page for a detailed list of the libscan library functions.As a plug-in module using gscan, which provides a complete graphical scanning interface. When passed the -p option, gscan writes scanned data to its standard output as a Stream TIFF file. After launching gscan with the -p option, applications can use the STIFF routines in libstiff to acquire the scanned data from the standard output of gscan.LBL="2"ID="91816"Installing Impressario SoftwareID="chap21"This chapter explains how to install the Impressario software. It gives product-specific information that supplements the ID="chap22"IDREF="29804" BOOK="IA_InstLicns" FILE="" HDG="29804" INFO=""IRIX Admin: Software Installation and Licensing
manual and the IDREF="96534" BOOK="PerSysAdmin" FILE="" HDG="96534" INFO=""Personal System Administration Guide
. This chapter should be used in conjunction with those guides to install the Impressario software.The following topics are discussed in this chapter:IDREF="59126" TYPE="TITLE""Impressario Products"IDREF="46043" TYPE="TITLE""Installation Software Prerequisites"IDREF="89109" TYPE="TITLE""Disk Space Requirements"IDREF="29383" TYPE="TITLE""Installing Impressario"IDREF="87579" TYPE="TITLE""Software Compatibility"NoteSee the Impressario release notes for the most up-to-date information on installing the Impressario software.LBL="" HELPID=""ID="59126"Impressario ProductsID="chap23"ID="chap24"IDREF="69666" TYPE="TABLE"Table 2-1 lists the products contained in Impressario 2.0. The Impressario release notes contain a complete list of the subsystems for each product.COLUMNS="2"LBL="2-1"Table 2-1 ID="69666"Impressario 2.0 ProductsID="chap25"LEFT="0" WIDTH="77"ProductLEFT="85" WIDTH="307"ContentsLEFT="0" WIDTH="77"impr_baseLEFT="85" WIDTH="307"Impressario base software. Includes the User Guide, reference pages, release
notes, and printer-driver file conversion filters.LEFT="0" WIDTH="77"impr_devLEFT="85" WIDTH="307"Impressario developers software. Includes the Developers guide, scanner
and printer developer libraries, and reference pagesLEFT="0" WIDTH="77"impr_ripLEFT="85" WIDTH="307"The Adobe CPSI PostScript Level 2 interpreter, its associated files and
reference pages. (rip is the acronym for Raster Image Processor.) The
PostScript interpreter requires a software license.LEFT="0" WIDTH="77"impr_rip_printersLEFT="85" WIDTH="307"Impressario printer drivers that require the impr_rip software. These driversprocess PostScript on the IRIX host and send raster data to the printer.LEFT="0" WIDTH="77"impr_serverLEFT="85" WIDTH="307"Impressario printer drivers that do not require the impr_rip software. These
drivers send PostScript directly to the printer for processing and, therefore,
do not need a host-based PostScript interpreter.LEFT="0" WIDTH="77"impr_scanLEFT="85" WIDTH="307" Impressario scanner drivers, gscan, and reference pages.NoteDeveloper information that was formerly contained in the Impressario 1.2 Developer's Kit is now in the release notes.After installing the Impressario software, you can use the versions command to list the subsystems. To list all the subsystems for impr_base, enterversions -av impr_baseTo list all the installed files, enterversions long impr_baseLBL="" HELPID=""ID="46043"Installation Software PrerequisitesID="chap26"ID="chap27"Your workstation must be running IRIX 6.2 or later with the Indigo Magic desktop to use Impressario 2.0. To determine the IRIX system release, enter the commandID="chap28"uname -aimpr_base.sw.il_imagesID="chap29" requires part of the il_eoe system. See the Impressario release notes for a complete list of Impressario prerequisites.LBL="" HELPID=""ID="89109"Disk Space RequirementsID="chap210"ID="chap211"See the Impressario release notes for current disk space requirements.If you are installing Impressario using inst, the subsystems marked "Default" are those that are installed if you use the go command. To install a different set of subsystems, use the install, remove, keep, and step commands in inst to customize the list of subsystems to be installed, then select the go command.LBL="" HELPID=""ID="29383"Installing ImpressarioID="chap212"To install Impressario, do the following:Install the Impressario software on your system.Connect the printer or scanner to the system.Configure the Impressario software for use with the printer or scanner.LBL="" HELPID=""Installing Impressario SoftwareID="chap213"All of the subsystems for Impressario can be installed using IRIX on a running system. You do not need to use the miniroot. Refer to the IDREF="29804" BOOK="IA_InstLicns" FILE="" HDG="29804" INFO=""IRIX Admin: Software Installation and Licensing
manual and the IDREF="96534" BOOK="PerSysAdmin" FILE="" HDG="96534" INFO=""Personal System Administration Guide
for complete installation instructions.LBL="" HELPID=""Connecting the Printer or ScannerID="chap214"To physically connect your printer or scanner, follow the instructions provided by the manufacturer.LBL="" HELPID=""Printer SupportID="chap215"Impressario 2.0 includes support for the following printers and plotters:Apple LaserWriterID="chap216"ID="chap217"ID="chap218"ID="chap219"ID="chap220"ID="chap221"« Plus, II, IINT, IINTX, IIf, and IIgHewlett-Packard DesignJet 650C, and 750CID="chap222"Hewlett-Packard DeskJet 500C, 550C, 560C, 660C, 850C, 855C, 1200C, 1600CID="chap223"ID="chap224"ID="chap225"Hewlett-Packard PaintJetID="chap226"ID="chap227"ID="chap228"« XL300Hewlett-Packard LaserJet IIP, IIP+, III, IIIP, 4, 4L, 4P, 4Plus, 4V, 4Si, 5L, 5P, and 5SiID="chap229"ID="chap230"ID="chap231"ID="chap232"ID="chap233"Lexmark Optra R, Rx, L, Lx, and LxiEpson Color Stylus, Stylus Pro, and Stylus Pro XLGenicomname='trade' font=symbol charset=fontspecific code=228
descr='[trade]' 7910, 7912, and 7916LBL="" HELPID=""Scanner SupportID="chap234"Impressario 2.0 includes support for the following scanners:Hewlett-Packard ScanJetID="chap235"« IIc, IIcx, 3c, and 4cRicoh FS2ID="chap236"MicroTek ScanMaker 600 ZSID="chap237"Sharp JX 320ID="chap238"Epson GT 6000ID="chap239"NoteSee the Impressario release notes for additional information on specific hardware installation requirements.LBL="" HELPID=""Configuring the Impressario SoftwareID="chap240"LBL="" HELPID=""Printer ConfigurationID="chap241"Impressario printer software is configured using the Printer Manager tool that comes with the IRIS System Manager. The Printer Manager can be accessed from the Toolchest System menu. See the ID="chap242"IDREF="96534" BOOK="PerSysAdmin" FILE="" HDG="96534" INFO=""Personal System Administration Guide
for details on installing printers.NoteAfter upgrading your system to Impressario 2.0, you must use the Printer Manager to delete and reinstall all your printers, including networked ones.LBL="" HELPID=""Scanner ConfigurationID="chap243"Impressario scanner software is configured using the Scanner Manager tool that comes with Impressario. The Scanner Manager can be accessed from either the System Manager or a shell. See the IDREF="61221" BOOK="Impr_UG" FILE="" HDG="61221" INFO=""Impressario User's Guide
for details on installing scanners.LBL="" HELPID=""ID="87579"Software CompatibilityThe design of IRIX 6.2 doesn't allow the use of COFF binaries. Because it requires IRIX 6.2, Impressario 2.0 can't run Impressario drivers that use COFF binaries. These includeSeikoPrint for Impressario 1.1the Ricoh FS2 for Impressario 1.1 scanner driverGenicomPrint 1.1 for Impressario 1.1 and GenicomPrint 1.2 for Impressario 1.1Tektronix PhaserPrint for Impressario 1.0NotePhaserPrint for Impressario 1.0 uses the obsolete CHUNKY data format. As of this writing, Tektronix does not intend to support Impressario 2.0. If you wish to use PhaserPrint for Impressario 1.0, do not update to IRIX 6.2 and Impressario 2.0.See chapter 5 of the Impressario release notes for more details on software compatibility.LBL="3"ID="26455"Printer DriversID="chap31"ID="chap32"This chapter provides an overview of printer driver processing, followed by a detailed analysis of an example printer driver. The required printer filter/driver options and the reserved and unreserved printer filter/driver options are also covered.The following topics are discussed in this chapter:IDREF="17188" TYPE="TITLE""Printer Driver Processing"IDREF="93789" TYPE="TITLE""Printer Driver Examples"IDREF="77047" TYPE="TITLE""The Filter/Driver Specification and psrip"NoteThe PostScript interpreter, psrip, has been upgraded to an Adobe Level II Configurable PostScript Interpreter (CPSI). Adobe Systems, Inc. imposes strict limitations on the use of the Configurable PostScript Interpreter by developers. Please refer to IDREF="38738" TYPE="TITLE"Appendix H, "Using the Adobe Configurable PostScript Interpreter," for details.TipPrinter application developers can skip to IDREF="20198" TYPE="TITLE"Chapter 6.LBL="" HELPID=""OverviewA printer driver must perform the following tasks:Receive and process an input file.Send formatted data to the printer or to standard out. (The driver can use standard out when sending data to the generic drivers phandler and nethandler.)Query the printer and receive status information. (This step is optional if phandler or nethandler is used.)Read and write the printer object database (POD) files.All printer drivers must read the POD files to determine printer-specific defaults and to maintain the active status file of the POD so that other clients can determine the printer's status. IDREF="20198" TYPE="TITLE"Chapter 6, "Printing Libraries," describes libpod, the library that provides an API to the POD. IDREF="64689" TYPE="TITLE"Appendix C, "Printer Object Database (POD) File Formats," defines the file formats for the printer configuration file, the printer status file, and the printer log file in the POD.LBL="" HELPID=""ID="17188"Printer Driver ProcessingIDREF="72399" TYPE="GRAPHIC"Figure 3-1IDREF="18829" TYPE="TEXT" provides an overview of printer driver processing. Note that this is a simplified overview; the actual steps might be more complex.ID="18829"FILE="chap3-1.gif" POSITION="INLINE" SCALE="FALSE"LBL="3-1"Figure 3-1 ID="72399"Printer Driver Processing OverviewLBL="" HELPID=""ID="93789"Printer Driver ExamplesID="chap33"Two example printer drivers are provided: laserjetPJL for HP LaserJet printers and phandlerID="chap34" for generic parallel printers. The source code files for ID="chap35"laserjetPJL are in the directory /usr/impressario/src/drivers/laserjetPJL and the source code files for phandler are in the directory /usr/impressario/src/drivers/phandler. Both drivers follow the steps shown in IDREF="18829" TYPE="TEXT"IDREF="72399" TYPE="GRAPHIC"Figure 3-1, but the laserjetPJL driver is more complex because it also performs data compression. Because this added complexity is not necessary for the example, the focus is on the phandler driver in this chapter.The example printer driver phandler checks the status of the parallel port while passing data through to the printer. It treats the input as a byte stream and updates the printer status file at various stages of processing.Among the include files in this program is ID="chap36"pod.h, which contains printer status error codes and other defined constants related to printing. The include file ID="chap37"plp.h contains information related to the parallel port.ID="chap38"LBL="" HELPID=""Program InvocationID="chap39"The command-line interface for phandler isphandler -P printer_name [options] [filename]Arguments:-P printer_nameThe name of the installed printer (required).filenameThe name of the file to send to the printer. Data is read from standard input if no filename is given.options can be one or more of the following:-eExit immediately on error. (The default is not to exit on error.)-wSuppress warning messages.-DEnable debugging. -D is the lowest level of detail, -D-D is the second level, and -D-D-D is the highest level of detail. The debugging information is appended to the log file.-L filenameUse filename as the log file for debugging information and errors. The default is to use standard error, which the System V, Release 3 lp spooler redirects to the spooler log file.-RReset the parallel port before sending data.-KIgnore interrupts.-IEnable sensing of the EOI pin. The default is to ignore the EOI pin.-B intSet the size of the internal transfer buffer to int bytes. The default is 1024. Larger buffers enable more page buffering, which may free upstream filters to do more processing while data is being sent to the printer.-sInvoke phandler to update the printer's status. Check the parallel port's status unless -u is specified. Update the paper size if -S is specified.-uUsed only with -s. Don't check the parallel port's status. This allows the driver to ignore the parallel port while it is updating the POD status file.-S stringSet the paper size (for example, A, A4, Legal) to string and update the POD status file for the printer.-d Send an ASCII Control-D (hexadecimal 0x4) at the end of the job.To invoke phandler to update the POD data base, enter this command:/usr/lib/print/phandler -P printername -s -u -K -S AThis use of phandler only updates the POD data base with the paper size. It ignores the parallel port status, and no information is sent to the parallel port. You normally use this command before invoking any filter that accesses the POD data base to insure that the filter gets the correct paper size.After updating the POD data base with the paper size, you could send a file to the parallel port with phandler like this:/usr/lib/print/text2ps -J printername textfile | \/usr/lib/print/phandler -P printername -K -S A -d Here, text2ps is used to convert an ASCII text file to a PostScript file. text2ps uses printername to access the POD and get printer-specific information, such as paper size. Other filters operate similarly to text2ps by accessing the POD for printer-specific information. This is why you run phandler to update the POD status before using a filter.The output of text2ps is piped to phandler, which sends it to the parallel port while monitoring the printer's status and updating the POD.LBL="" HELPID=""Program ProcessingThis section contains a detailed discussion of the phandler driver. A more detailed example driver is supplied in the /usr/impressario/src/drivers/laserjetPJL directory.NoteThe Impressario guidelines strictly require drivers to retry errors. Error exits are to be avoided whenever possible so that print jobs do not disappear before the user has a chance to fix the error condition.LBL="" HELPID=""Do the Initial ProcessingParse the command-line arguments with ID="chap310"getopts.Read the printer status file. If phandler cannot open the status file, it exits with an error message.LBL="" HELPID=""Open the Printer PortOpen the port. If there is an error and you requested exit on error when invoking phandler, then the program writes an error message and exits. Otherwise, when an error occurs, the program continues trying to open the port. It checks every n seconds (where n is the value of error_retry_wait) and writes an error message to the log file after each failed attempt to open the port.If phandler successfully opens the port, it updates the current printer status to "Busy" in the printer active status file. If the command line contained the -s option (status only), then phandler exits after updating the status. (The kernel closes the port when it exits the program.)LBL="" HELPID=""Allocate and Set Up the BufferAllocate and set up the buffer. If phandler cannot allocate the buffer, the program exits with an error message. (It exits only because memory allocation errors are very rarely recoverable.)LBL="" HELPID=""Update libpod StatusUse the fork system call to create a child that updates the printer status.LBL="" HELPID=""Read, Process, and Send Data to the PrinterBegin reading from the input and begin sending data to the parallel port.Your driver will probably need to process the input data into an appropriate printable format before sending the data to the printer.If an unrecoverable error occurs while writing to the parallel port, write an error message to the log file, write the faulted state to the printer status configuration file, and exit.If the input file is empty or unreadable, write an error message to the log file, update the status file, and exit.The driver uses signal handling to ensure that it is not interrupted in "critical regions," during which an interrupt could destroy vital files or the printer state.LBL="" HELPID=""Cleaning Up and ExitingWhen printing is complete, update the printer status configuration file to "Idle," terminate the child status process, and exit.LBL="" HELPID=""ID="77047"The Filter/Driver Specification and psripID="chap311"ID="chap312"The command-line options listed in this section must be implemented as specified for any printing filter or driver to be compatible with Impressario. Switch letters have been chosen to maximize the intuitive correlation with function. Additional functionality beyond that listed here must use unreserved switch settings. Please note the following points:All switches are case sensitive. That is, -P does not have the same meaning as -p.Printer drivers must accept and ignore all reserved options that are not supported.Printer drivers must conform to getopts conventions. (See getopts(2) for more information.)Multiple options on a single line have right-to-left precedence. For example:-n 1 -n 2has the same effect as-n 2The STIFF file passed to a printer driver may have command-line options embedded in it by psrip, a program that converts PostScript files to STIFF files. Drivers that accept input from psrip must accept and parse these command-line options. A good example is a PostScript file that contains a PostScript command to print 5 copies. psrip parses that PostScript command and embeds -n5 in the STIFF file header. This header file information tells the printer driver to print 5 copies. The laserjetPJL example driver demonstrates how to parse command-line options embedded in a STIFF file. IDREF="68392" TYPE="TITLE"Appendix A, "Stream TIFF Data Format," details the STIFF header format.LBL="" HELPID=""Required OptionsID="chap313"ID="chap314"These switches must be supported by all drivers:-eExit immediately on fault without waiting for faults to clear. The default behavior is to wait indefinitely for faults to clear, polling the device at the error-retry intervals specified in the POD configuration file. This option is used when only a quick query should be done.-sUpdate the status file. Exit only after successfully doing so. This switch has the highest precedence. If the -e switch is given, exit after one try at reading status.-wDo not report warnings in the status file. Report errors only.-DEnable debugging information. Optionally, more -D switches increase the level of debugging detail. For example, entering-D -Denables a second level of debugging detail. At least one level of debugging must be supported.-P stringThe value of string defines the printer name. The printer name is used to find the POD. The printer name is the name given to the printer at installation time. See the libpod(3) reference page for more information. This option is also a required option whenever the driver is invoked.Impressario printer drivers must read the libpod printer object database todetermine defaultsmaintain the active status portion of the POD databaseenable other clients to determine printer statusLBL="" HELPID=""Reserved OptionsID="chap315"The following options are reserved and are to be implemented by drivers whose hardware supports them, or by inline filters that process the options before the driver is invoked. You need not implement all options, but every driver must accept or ignore any unimplemented options on this list.Raster-specific options include the following:ID="chap316"ID="chap317"-fFlip the image, as if in a mirror. The image is rotated horizontally about the y-axis. Useful for transparencies or decals.-p intScale the image as if it were being printed on a device with the designated resolution specified in int pixels per inch. This is a convenience switch, since the same effect can be obtained by computing the appropriate scale factor for the image size and destination resolution.-r intRotate the image counter-clockwise by an angle specified in int degrees. Values outside the range 0-359 should be accepted and modulo converted to a value between 0-359.-z floatZoom the image using proportional scaling, where the floating-point argument is nonnegative. Some values are given below:COLUMNS="2"LEFT="0" WIDTH="49"0.0LEFT="55" WIDTH="115"Do not zoom the image.LEFT="0" WIDTH="49"0.5LEFT="55" WIDTH="115"Fill one-half of one page.LEFT="0" WIDTH="49"1.0LEFT="55" WIDTH="115"Fill one page.NoteThe image aspect ratio must be preserved. Future implementations may extend this to multiple pages. For example, 2.0 would mean fill a 2-by-2 page array.Engine-specific options include the following:ID="chap318"ID="chap319"-q intQuality mode. Set the engine-specific quality mode. This should be a nonnegative integer, with greater values indicating higher quality.-n intThe number of copies to be printed, a positive integer.-tGenerate a test print. The test print should confirm that all marking media are present and functional.-m intManual feed request. Wait ID="chap320"MediaWaitTimeout seconds for manual feed. Give up after ID="chap321"MediaWaitTimeout seconds and print anyway on the available media. See the POD for these values. Giving up is important for shared printers.-o intRequest a specific output medium:COLUMNS="2"LEFT="0" WIDTH="49"0LEFT="55" WIDTH="135"paper or a reflective mediumLEFT="0" WIDTH="49"1LEFT="55" WIDTH="135"transparenciesOther media types may be supported; see the libpod(4) reference pages.Output-specific options include the following:ID="chap322"ID="chap323"-L filenameLog errors to filename instead of standard error. The file specified should be opened in append mode. If the file cannot be opened, errors should be reported to standard error instead.-O filenameOutput data to filename instead of the device port or standard output. The file specified should be opened. If the file cannot be opened, data should instead be written to the device or standard output, as appropriate. If this option is used, all status reporting is disabled, because the printer driver is not communicating with the actual device.LBL="" HELPID=""Unreserved OptionsID="chap324"ID="chap325"The switches listed below are not reserved and can be used for device-specific options:Lowercase: a, b, c, d, g, h, i, j, k, l, u, v, x, yUppercase: A, B, C, E, F, G, H, I, J, K, M, N, Q, R, S, T, U, V, W, X, Y, ZLBL="4"ID="35103"Printer Model FilesID="chap41"This chapter discusses the printer model files and describes the modifications to be made by printer-driver developers to the printer model file template.The following major topics are discussed in this chapter:IDREF="23233" TYPE="TITLE""Overview"IDREF="30372" TYPE="TITLE""Command-Line Arguments"IDREF="10825" TYPE="TITLE""Template Model File Execution"IDREF="13511" TYPE="TITLE""Printer-Specific Options"IDREF="69817" TYPE="TITLE""Developer-Supplied Model File Additions"LBL="" HELPID=""ID="23233"OverviewModel files are Bourne shell scripts that form an interface between the System V, Release 3 spooling system and the printer. Each printer has its own model file, which is customized by the printer installation tools when the printer is installed. The customized copy of the printer model file is the interface file. The interface file is invoked by the spooling scheduler lpsched when the printer is ready to accept a new print job. The interface file sets up printer-specific options, calls filters, and invokes the printer driver.System V model files differ greatly from BSD /etc/printcap entries. The reader unfamiliar with System V spooling should refer to the IDREF="80575" BOOK="IA_Periphrls" FILE="" HDG="80575" INFO=""IRIX Admin: Peripheral Devices
manual for more information.LBL="" HELPID=""ID="30372"Command-Line ArgumentsID="chap42"ID="chap43"The model file expects these command-line arguments from lpsched in the order listed:1job sequence ID numberID="chap44"2user login nameID="chap45"3job titleID="chap46"4number of copies to be printedID="chap47"5-o printer options6-nname(s) of the file(s) to be printedThe end user does not invoke the model file manually; it is invoked only through lpsched. If you want to check for gross syntax errors, you can do this quickly by running the model file with dummy arguments such as:laserjetPJL_model a b c d eNot all errors can be found this way, since the model file does not run to completion, but this does provide a quick test for gross syntax errors. If errors are found, putting the -x flag at the end of the first line in the model file may help debug the error. See the sh(1) reference pages for more details on debugging Bourne shell scripts.LBL="" HELPID=""ID="10825"Template Model File ExecutionID="chap48"This section explains how the Impressario model files work.The source code for the template laserjetPJL_model file is located in the directory /usr/impressario/src/models. The main steps in the template model file are shown below and described in more detail in the following sections:Declare global and external variables and define convenience functions.Interpret and store the command-line options.Verify that the prerequisites are in place.Set the output device driver, which can be either a driver for the parallel port or a driver for a network card that is installed in a printer.Invoke the driver to update the POD status file with the current printer state and the current job setting. NoteThis is an important step. All filters use the status file to determine what parameters to use. The driver must ensure that the POD status file is absolutely up to date before the first filter is run, or a change in printer status between jobs could compromise the next job.Start the active icon tagging subprocess.If pages stack face down, print a banner page if requested.Use filters to convert the submitted file to the data type required by the printer driver.Invoke the printer driver with the converted data.Repeat steps 8 and 9 for each file to be printed and report any errors encountered to standard error.If pages stack face up, print a banner page if requested.Clean up after the job and exit with an appropriate exit code.LBL="" HELPID=""Declaring VariablesThe steps given below tell you what variables to declare. Note that variable names are in all uppercase letters. Those variables are exported for use by the filters invoked when converting input files into printable data. See the fileconvert(1) reference page for more information.Define NAME and TYPE. If the type is not defined, then the model file writes an error message and exits.Append the standard error output from the filters and driver to the spooler log file.Define the file paths, directory paths, and Boolean flags used in the model file.Define the locations and options for all filters. (The model file checks to make sure that the printer-specific driver exists and that the spooler log file is writable. If these conditions are not met, the model file writes an error message and exits.)LBL="" HELPID=""Defining Convenience FunctionsID="chap49"The next portion of the model file contains various convenience functions used within the model file. The convenience functions listed in IDREF="15961" TYPE="TABLE"Table 4-1 are routines contained within the model file. These routines are used for parsing the -o options and for various utility functions.COLUMNS="2"LBL="4-1"Table 4-1 ID="15961" (continued) Convenience FunctionsLEFT="0" WIDTH="110"Function NameLEFT="115" WIDTH="231"DescriptionLEFT="0" WIDTH="110"BeginTagging()LEFT="115" WIDTH="231"Sets up the tagging job that monitors the printer's status.LEFT="0" WIDTH="110"CleanUpAfterJob()LEFT="115" WIDTH="231"Does any cleanup needed at the end of the job.LEFT="0" WIDTH="110"EndTagging()LEFT="115" WIDTH="231"Ends the tagging of the printer.LEFT="0" WIDTH="110"ParseOptions()LEFT="115" WIDTH="231"Parses the -o command-line options and sets appropriate
variables. Expects the command-line options string as the
first argument.LEFT="0" WIDTH="110"PrintBannerPage()LEFT="115" WIDTH="231"Prints a banner page.LEFT="0" WIDTH="110"PrintMessage()LEFT="115" WIDTH="231"Prints its arguments as text on the printer. Used to report
errors to the user. Accepts any number of arguments.LEFT="0" WIDTH="110"ReportBadFile()LEFT="115" WIDTH="231"Reports unknown file type to the printer and to the
spooler log. Expects the filename as the first argument
and the file type as the second argument.LEFT="0" WIDTH="110"ReportUnknownOption()LEFT="115" WIDTH="231"Reports an error when an unknown option is parsed.
Expects the unknown option as the first argument.LEFT="0" WIDTH="110"SetCancelTrap()LEFT="115" WIDTH="231"Sets up the trap command for the signals SIGHUP,
SIGINT, and SIGTERM.LEFT="0" WIDTH="110"SetDebug()LEFT="115" WIDTH="231"Turns on debugging mode for all filters and drivers.LEFT="0" WIDTH="110"SetDeviceDriver()LEFT="115" WIDTH="231"Sets the output device driver to a parallel port driver or
to a driver for a network card installed in a printer.LEFT="0" WIDTH="110"TestExitStatus()LEFT="115" WIDTH="231"Interprets exit status from the last command and sends
error message to both the spooler log and the printer if
needed. Expects the exit code of the last command as the
first argument, a string describing the last command as
the second argument, and the file in question as the third.LBL="" HELPID=""Processing Command-Line ArgumentsID="chap410"The template model file follows these steps to process command-line arguments:Retrieve the command-line arguments.Set up the cancellation signal handler for SIGHUP, SIGINT, and SIGTERM. This allows the user to cater the job cancellation signal sent by the spooler and clean up.Parse the options passed with the -o switch.Set the device driver.If the verbose switch is set, send a message to the spooler log that the job has begun filtering.Call the printer status and communications driver to update the status database before job filtering begins.Start the tagging subprocess to tag the printer's workspace icon with the appropriate print-engine type and status.LBL="" HELPID=""Printing Banner PageID="chap411"The model file prints a banner page is printed if the banner switch is set. (The banner page may be printed last for face-up stacking printers.)LBL="" HELPID=""Using Filters to Process FilesThe fileconvert command automatically determines the file type of each file using the Indigo Magic file typing rule database. (See the reference pages for ftr(1) and fileconvert.) If a fast text path exists, and the user has not requested options that require the slower path, then the file is converted using the fast text path. Otherwise, the normal fileconvert path is used. See the template model file for specifics.fileconvert produces a shell command string that, when executed, produces the requested data type on standard output.If the file could not be converted, ReportBadFile() is called; otherwise the fileconvert shell program is executed and the output piped to the printer driver.TestExitStatus() is called to test whether the driver reported an error.LBL="" HELPID=""Cleaning Up and ExitingAfter the printing is complete, perform any needed cleanup.End the tagging subprocess.Append an ending message to the log file if the debug switch is set.If there were unsupported file types in the list of files to be processed, exit the model file with an easily understood error code.LBL="" HELPID=""ID="13511"Printer-Specific OptionsID="chap412"The -o option to the spooler allows model files to accept a variety of non-spooler options. These are the options specified with -o on the lp command line. It is these options that are produced by the graphical printer options panel.Impressario defines a number of general file filtering options for the convenience of the end user, and reserves those option names.The reserved options are listed in IDREF="44373" TYPE="TABLE"Table 4-2 in alphabetical order. Their meanings should not be changed by printer driver developers. Developers should choose short, understandable option names for any additional options. These options may be seen by end users, so they should not be verbose.COLUMNS="2"LBL="4-2"Table 4-2 ID="44373" (continued) Reserved Option NamesLEFT="0" WIDTH="65"Option NameLEFT="70" WIDTH="266"DescriptionLEFT="0" WIDTH="65"bannerLEFT="70" WIDTH="266"Prints a banner page.LEFT="0" WIDTH="65"bestfitLEFT="70" WIDTH="266"Uses the best fit orientation for image files (default is on).LEFT="0" WIDTH="65"bottommarginLEFT="70" WIDTH="266"Sets the bottom margin size for text.LEFT="0" WIDTH="65"columnsLEFT="70" WIDTH="266"Sets the number of columns on the page for text.LEFT="0" WIDTH="65"debugLEFT="70" WIDTH="266"Causes filters to report debugging information (default is off).LEFT="0" WIDTH="65"duplexLEFT="70" WIDTH="266"Turns duplex on or off.LEFT="0" WIDTH="65"flipLEFT="70" WIDTH="266"Flips the image, producing a mirror image.LEFT="0" WIDTH="65"fontnameLEFT="70" WIDTH="266"Uses a specified font name for text.LEFT="0" WIDTH="65"fontsizeLEFT="70" WIDTH="266"Uses a specified font size for text.LEFT="0" WIDTH="65"gammaLEFT="70" WIDTH="266"Uses a specified value for image gamma correction.LEFT="0" WIDTH="65"gaudyLEFT="70" WIDTH="266"Uses a fancy page header for formatted text.LEFT="0" WIDTH="65"halftoneLEFT="70" WIDTH="266"Sets the halftone or dithering option to be used.LEFT="0" WIDTH="65"intrayLEFT="70" WIDTH="266"Specifies the input media source (same as the tray option).LEFT="0" WIDTH="65"landscapeLEFT="70" WIDTH="266"Uses landscape page orientation for text.LEFT="0" WIDTH="65"leftmarginLEFT="70" WIDTH="266"Sets the left margin size for text.LEFT="0" WIDTH="65"manpageLEFT="70" WIDTH="266"Indicates the preformatted manual page to be printed.LEFT="0" WIDTH="65"manualLEFT="70" WIDTH="266"Sets manual feed.LEFT="0" WIDTH="65"nobannerLEFT="70" WIDTH="266"Sets the "do not print a banner page" option.LEFT="0" WIDTH="65"nogaudyLEFT="70" WIDTH="266"Sets the "do not use fancy page header for formatted text" option.LEFT="0" WIDTH="65"noverboseLEFT="70" WIDTH="266"Sets the "do not print verbose messages in the spooler log file"
option (same as the -h option).LEFT="0" WIDTH="65"numberpagesLEFT="70" WIDTH="266"Sets the number of text pages.LEFT="0" WIDTH="65"outtrayLEFT="70" WIDTH="266"Specifies the output media source.LEFT="0" WIDTH="65"papersizeLEFT="70" WIDTH="266"Selects the paper size.LEFT="0" WIDTH="65"portraitLEFT="70" WIDTH="266"Uses portrait page orientation for text.LEFT="0" WIDTH="65"ppiLEFT="70" WIDTH="266"Scales the final image size to match the specified original image
resolution, in pixels per inch.LEFT="0" WIDTH="65"psevenpageLEFT="70" WIDTH="266"Prints even pages only (PostScript).LEFT="0" WIDTH="65"psoddpageLEFT="70" WIDTH="266"Prints odd pages only (PostScript).LEFT="0" WIDTH="65"pspagerangeLEFT="70" WIDTH="266"Prints the specified page range (PostScript).LEFT="0" WIDTH="65"psreversepageLEFT="70" WIDTH="266"Reverses the page order (PostScript).LEFT="0" WIDTH="65"resolutionLEFT="70" WIDTH="266"Sets x and y resolutions (for resolution-switchable printers).LEFT="0" WIDTH="65"reversepagesLEFT="70" WIDTH="266"Reverses text document page order (prints the last page first).LEFT="0" WIDTH="65"rightmarginLEFT="70" WIDTH="266"Sets the right margin size for text.LEFT="0" WIDTH="65"rotateLEFT="70" WIDTH="266"Rotates the image clockwise in 90 degree increments. LEFT="0" WIDTH="65"topmarginLEFT="70" WIDTH="266"Sets the top margin size for text.LEFT="0" WIDTH="65"trayLEFT="70" WIDTH="266"Specifies the input media source.LEFT="0" WIDTH="65"verboseLEFT="70" WIDTH="266"Records debugging messages in the spooler log file.LEFT="0" WIDTH="65"zoomLEFT="70" WIDTH="266"Scales the image to fit the page (default is a scale of 1.0).LBL="" HELPID=""ID="69817"Developer-Supplied Model File AdditionsPrinter-driver developers must customize the model file template supplied by Silicon Graphics to the specifications of their printers. The template model is located in the file /usr/impressario/src/models/template_model. This code is the same as the code in the ID="chap413"laserjetPJL_model file so that developers can have a working, debugged example from which to begin.The following ten items must be specified by you. They are listed and explained in the order in which they appear in the model file template.Printer name.Device interface.Printer type.GUI class.Printer-specific filter/driver.Debug routine.Cleanup routine.Printer-specific banner page.Printer-specific filtering options.Fast path for text.NoteAll items that must be modified by the developer have been marked with "#XXX" in the model file. Search for and remove these markers as you progress to be sure all necessary modifications have been made.LBL="" HELPID=""Printer NameID="chap414"ID="chap415"The NAME variable identifies the real printer name, such as "HP DeskJet 500C." NAME contains the string that is presented to the end user in the Printer Manager's graphical printer install tool. Multiple NAME variables are allowed on separate lines if the model file can support more than one printer.LBL="" HELPID=""Device InterfaceID="chap416"ID="chap417"ID="chap418"ID="chap419"The DEVICE variable identifies the hardware interface where the printer is attached. The value is used by the printer install tool to present models by connection type. Multiple connections are supported. (Use multiple lines for multiple devices; that is, simply repeat the line for each different device.) The values currently allowed are SERIAL, SCSI, CENTRONICS, NETPRINTER, and REMOTE. Obsolete types that should not be used are VERSATEC and TEK.ID="chap420"ID="chap421"ID="chap422"ID="chap423"LBL="" HELPID=""Printer TypeID="chap424"The TYPE variable identifies the printer type. This information is used by the Print Manager, routeprint, libspool functions, and other system software, including the active icons subsystem. ID="chap425"ID="chap426"ID="chap427"IDREF="56422" TYPE="TABLE"Table 4-3 shows the values allowed for the TYPE variable. Obsolete types are Dumb, Color, and PostScript.COLUMNS="3"LBL="4-3"Table 4-3 ID="56422"Printer Type SpecificationsID="chap428"ID="chap429"ID="chap430"ID="chap431"ID="chap432"ID="chap433"LEFT="0" WIDTH="77"TYPE ValueLEFT="85" WIDTH="146"Data Types AcceptedLEFT="240" WIDTH="125"Printer ExamplesLEFT="0" WIDTH="77"RasterLEFT="85" WIDTH="146"At least text, .SGI image, PostScriptLEFT="240" WIDTH="125"HP LaserJetLEFT="0" WIDTH="77"ColorRasterLEFT="85" WIDTH="146"At least text, .SGI image, PostScriptLEFT="240" WIDTH="125"Tektronix Phaser II SXLEFT="0" WIDTH="77"PlotterLEFT="85" WIDTH="146"HP-GL onlyLEFT="240" WIDTH="125"HP 7550ALEFT="0" WIDTH="77"ColorPostScriptLEFT="85" WIDTH="146"At least text, .SGI image, PostScriptLEFT="240" WIDTH="125"Tektronix Phaser II PXiLEFT="0" WIDTH="77"MonoPostScriptLEFT="85" WIDTH="146"At least text, .SGI image, PostScriptLEFT="240" WIDTH="125"LaserWriter II NTXLBL="" HELPID=""GUI ClassThe value of this variable is the name of the resource file for the graphical options panel. This value must match the #define GUI_CLASS in the options panel gui_class.h. If an options panel is not provided, do not specify a value for this variable.LBL="" HELPID=""Printer-Specific Filter/DriverID="chap434"The file laserjetPJL.c contains an example of a complete printer driver. This driver is used in the /usr/impressario/src/models/laserjetPJL_model file. For comments about the model file, see the /usr/impressario/src/models/template_model.README file.LBL="" HELPID=""Debug RoutineID="chap435"ID="chap436"To turn on debugging for developer-supplied filters, modify SetDebug() to set the debug switch (-D) for each filter.LBL="" HELPID=""Cleanup RoutineSome developers may need to perform some cleanup at the end of each job. If so, add this cleanup to the routine CleanUpAfterJob() in the model file. To make this step easier, the use of temporary or intermediate files is strongly discouraged.LBL="" HELPID=""Printer-Specific Banner PageID="chap437"ID="chap438"ID="chap439"It is recommended that you do not modify this routine. However, to create a customized banner page that uses printer features such as page counts or graphics, modify PrintBannerPage() as required. The banner page should not unduly slow down the printing process, and customized banner pages should include at least as much job-specific information as the default banner page: job ID, user name, job title, date and time, and the filename(s).If your printer is unlikely to be shared, or has high per-page costs, you may want to turn off banner pages by default. In this case, set the variable banner to zero (0). However, users can still choose to print a banner page.Printers that stack pages face down should print the banner page before any files, while those that stack pages face up should print the banner page last. This is handled automatically if the faceup variable is set appropriately.LBL="" HELPID=""Printer-Specific Filtering OptionsID="chap440"ID="chap441"The ParseOptions() routine parses the -o command-line options and sets appropriate global variables. This routine contains many general options, and developer-specific options can be added if required. However, developer-supplied options must not duplicate Silicon Graphics reserved words. See IDREF="13511" TYPE="TITLE""Printer-Specific Options" for a complete, alphabetized list of existing options.It is recommended that any developer-specific options be full-word names to improve the readability of the stored settings files and to reduce name-space conflicts. This also aids users who use command-line interfaces to printing. However, option names should be kept brief.LBL="" HELPID=""Fast Path for TextID="chap442"You should modify the path in the file filtering section of the model file to use native text support if your printer supports native text printing that is faster than PostScript printing. Users, however, must still have access to all PostScript formatting options. Do not disable the slower PostScript path.LBL="5"ID="20688"Printer Graphical Options PanelID="chap51"This chapter discusses the graphical options panel, which visually showcases a printer's features.The following major topics are discussed in this chapter:IDREF="49897" TYPE="TITLE""Graphical Options Panel Layout"IDREF="26733" TYPE="TITLE""Options Handling"IDREF="41664" TYPE="TITLE""Graphical Options Panel Development"IDREF="80585" TYPE="TITLE""Graphical Options Panel Naming"IDREF="25641" TYPE="TITLE""Graphical Options Panel Installation"IDREF="82492" TYPE="TITLE""Invocation by the PrintBox Widget"IDREF="20534" TYPE="TITLE""Standalone Invocation for Testing"IDREF="63908" TYPE="TITLE""Termination by the PrintBox Widget"LBL="" HELPID=""OverviewImpressario provides the PrintBox widget for submitting print jobs from Motif applications. This widget is contained in the library ID="chap52"ID="chap53"libprintui(3X). The PrintBox widget is used by the glp or PrintPanel command and a number of other applications to provide their printing capability. In addition to providing graphical selection of System V print job submission options, the widget provides the graphical options panel for graphical selection of printer-specific options.A graphical options panel allows the printer-driver developer to showcase the unique features of a printer in an intuitive graphical panel. The graphical options panel program is invoked by the PrintBox widget in applications, by the end user via glp, or by the Printer Manager in the System Toolchest. The Graphical Options Panel Specification located in the /usr/impressario/doc directory provides the information necessary to create and integrate a graphical options panel. Graphical options panels are standalone executable programs that are stored in a standard directory known to the Impressario printing tools. Therefore, the graphical options panels are automatically available to users of Impressario printing tools. The rules for developing a graphical options panel are straightforward and do not require any interprocess communication or similar complex procedures. In fact, we strongly discourage any network dependencies because not every Impressario printer is on a network.LBL="" HELPID=""ID="49897"Graphical Options Panel LayoutID="chap54"A graphical options panel most often consists of a single window. This window usually contains two sections, an options section and an action area. We strongly recommend that you keep options panels simple to avoid both complex code and complicated documentation.The options section contains all printer-specific option controls. This area is often divided into groups of option controls, where each group represents a specific input file type. Most options sections contain controls for text files, bitmap image files, and PostScript files. The options section also contains a general options section. Because there are often a large number of controls in the options section, you should use a scrolled window to limit the graphical options panel window to a reasonable size. IDREF="33258" TYPE="GRAPHIC"Figure 5-1 shows an example of a graphical printer options panel.FILE="fig5-1.gif" POSITION="INLINE" SCALE="FALSE"LBL="5-1"Figure 5-1 ID="33258"Graphical Printer Options PanelThe action area is located at the bottom of the graphical options panel window and consists of a number of push buttons. The first three are required:ID="chap55"OKOutput the option string to standard out and terminate the program.ApplyOutput the option string to standard out; do not terminate the program.CancelTerminate the program without any option string output.HelpProvide printer-specific options help.Group buttons together on the right side of the action area. The width of all buttons should be equal. The leftmost button should be OK followed by Apply, Cancel, and Help. Place any additional buttons between the Apply and Cancel buttons. Note that the supplied template makes this happen automatically.LBL="" HELPID=""ID="26733"Options HandlingID="chap56"If printer-specific options have been passed to the graphical options panel on the command line, the program must interpret these options and initialize its options-section controls to reflect the command-line options. Options not recognized by the graphical options panel must be preserved and prepended to the output option string.When the OK or Apply button is activated, the graphical options panel program must form a valid System V printer option string based on its GUI settings, and print this string to its standard output.LBL="" HELPID=""ID="41664"Graphical Options Panel DevelopmentID="chap57"The directory /usr/impressario/src/gui_models contains example source code for a graphical options panel. Begin with this code and add your printer-specific options. Do not start from scratch! You will waste valuable development time and may create inconsistencies. Benefit from others' experience and begin with the template.Create the graphical options panel with the OSF/Motif UIname='trade' font=symbol charset=fontspecific code=228
descr='[trade]' toolkit. Starting with Impressario 1.2, your graphical model file can have its own application resource file. While the resource file can be given any name, Silicon Graphics recommends that the name represent the printer model name and have its first letter capitalized. For example, the application resource file for the HP LaserJet graphical model file is called ID="chap58"LaserJetPJL. The name chosen for the resource file must be specified in the gui_class.h header file and must also be specified in the printer model file as the value of the GUI_CLASS variable. Your installation media must place the resource file in the directory /usr/lib/X11/app-defaults.To match the look and feel of the PrintPanel program (glp) and other graphical options panels, the application resource file should include the following resources:COLUMNS="2"LEFT="0" WIDTH="99"*useSchemes:LEFT="105" WIDTH="90"allLEFT="0" WIDTH="99"*schemeFileList:LEFT="105" WIDTH="90"SgiSpecLEFT="0" WIDTH="99"*sgiMode:LEFT="105" WIDTH="90"TrueTo facilitate localization of the options panel for international customers, all label strings and messages should be placed in the application resource file rather than being hard-coded into the program.The graphical model files must consist of a single executable program and its application resource file. The model files are restricted to these because the printer installation tools install only an executable and its resource file during network printer installation.LBL="" HELPID=""ID="80585"Graphical Options Panel NamingID="chap59"The graphical options panel must be given the exact same name as its printer's model file, followed by the suffix .gui. For example, if the printer model file for an HP DeskJet 500C printer is called deskjet_model, then the graphical options panel must be given the name ID="chap510"deskjet_model.gui. If the graphical options panel is given a name that differs from the model filename, it will not be installed by the printer install tools when a new printer is installed on a system.LBL="" HELPID=""ID="25641"Graphical Options Panel InstallationID="chap511"All graphical options panel programs must be installed by your installation media in the directory /var/spool/lp/gui_model or /var/spool/lp/gui_model/ELFAll programs compiled on systems running IRIX 5.0 or later are ELF executables.
. These directories are where the printer installation software searches for the programs. COFF executables must be installed in the directory /var/spool/lp/gui_model. The executable should be owned by lp and should be a member of the group lp. The file permissions of the executable should be set to 0755.NoteYou must always supply an ELF executable. COFF executables are not supported in IRIX 6.2, and are necessary only if you wish to support IRIX 4.0.5 systems.LBL="" HELPID=""ID="82492"Invocation by the PrintBox WidgetID="chap512"The graphical options panel is invoked by the PrintBox widget or the Printer Manager. The graphical options panel is always invoked with the command-line arguments listed in ID="chap513"IDREF="77033" TYPE="TABLE"Table 5-1. Note that the options are almost identical to those passed to your spooler model file.COLUMNS="2"LBL="5-1"Table 5-1 ID="77033"Command-Line ArgumentsLEFT="0" WIDTH="43"ArgumentLEFT="50" WIDTH="162"DescriptionLEFT="0" WIDTH="43"argv[0]LEFT="50" WIDTH="162"Printer nameLEFT="0" WIDTH="43"argv[1]LEFT="50" WIDTH="162"User nameLEFT="0" WIDTH="43"argv[2]LEFT="50" WIDTH="162"Filename(s) stringLEFT="0" WIDTH="43"argv[3]LEFT="50" WIDTH="162"Printer-specific option string (optional)LEFT="0" WIDTH="43"argv[4-n]LEFT="50" WIDTH="162"Xt options (optional)Any Xt options may be specified as argv[4] or greater. If there are no printer-specific options for argv[3], the empty string ("") is passed as argv[3]. If no filenames are specified, the empty string is also passed as argv[2].ID="chap514"LBL="" HELPID=""ID="20534"Standalone Invocation for TestingTo test a graphical options panel during development, it may be run as a standalone executable from the UNIX command line. Invoke the graphical options panel by entering[executable name] [any valid user name] ""For example, if the executable program is called laserjetPJL_model.gui, and "joe" is a valid user name on the system, then the program can be executed from the command line by entering:laserjetPJL_model.gui joe ""When debugging, it often helps to invoke the graphical options panel from the shell and repeatedly test the options string that is generated when the Apply button is pushed. Once the options string is properly generated, test for proper parsing of the input options by invoking the graphical options panel with various options strings, especially those output by your panel. Be especially careful that all widgets are set properly when, upon startup, the panel is passed a string that sets options to non-default values.LBL="" HELPID=""ID="63908"Termination by the PrintBox WidgetID="chap515"Applications terminate the graphical options panel using a SIGHUP signal. The graphical options panel should exit promptly upon receipt of this signal.LBL="" HELPID=""Additional InformationFor additional information, please read the online specification found in /usr/impressario/doc/gui_model.spec.The template was intended to make the creation of these panels easier. If you find the process difficult, please check the template documentation and the convenience routines in the support files. There may be a solution already provided.LBL="6"ID="20198"Printing LibrariesID="chap61"This chapter describes the printing libraries used by Impressario printer drivers, filters, and applications.Three printing libraries are described in this chapter:IDREF="65070" TYPE="TITLE""The libspool Library" is a C application program interface (API) to the UNIX printer spooling systems.IDREF="45357" TYPE="TITLE""The libprintui Library" is a C-language API to the PrintBox, a widget compatible with Motif.IDREF="65271" TYPE="TITLE""The libpod Library" is a C-language API to the printer object database (POD).In addition to the above libraries, there are two libraries described in the appendices that are also used by printer drivers and filters:IDREF="68392" TYPE="TITLE"Appendix A, "Stream TIFF Data Format," describes libstiff, a C-language API for reading and writing the STIFF (Stream TIFF) data file format.IDREF="79172" TYPE="TITLE"Appendix B, "Silicon Graphics Image File Format API," describes libimp, a C-language API for reading and writing Silicon Graphics Image format files.LBL="" HELPID=""The ID="65070"libspool LibraryID="chap62"The libspool library is a C application program interface to the UNIX printer spooling systems. There are two common UNIX printer spooling systems, System V and Berkeley Software Distribution (BSD). While these spooling systems provide essentially the same capabilities, each has its own command set and neither provides a C-language API. The libspool library provides a single, common API to both spooling systems. The functions provided by libspool include submission and cancellation of print jobs, and control and reading of print queues.ID="chap63"ID="chap64"LBL="" HELPID=""Compiling Programs With libspoolID="chap65"Programs that call libspool functions must include spool.h, the header file in the /usr/include directory. Use the following #include directive:#include <spool.h>The programs must also link with the libspool.a library located in /usr/lib. Here is an example of the complete cc compiler command line:cc -o myprog myprog.c -lspool LBL="" HELPID=""libspool Library FunctionsID="chap66"IDREF="49050" TYPE="TABLE"Table 6-1 lists the libspool functions by purpose.COLUMNS="3"LBL="6-1"Table 6-1 ID="49050"Summary of libspool FunctionsID="chap67"LEFT="0" WIDTH="112"TaskLEFT="120" WIDTH="123"Function NameLEFT="250" WIDTH="146"PurposeLEFT="0" WIDTH="112"Spooling System SelectionLEFT="120" WIDTH="123"SLSetSpooler()SLGetSpooler()LEFT="250" WIDTH="146"Set the default spooling system.Get the default spooling system and
available systems.LEFT="0" WIDTH="112"Printer InformationLEFT="120" WIDTH="123"SLGetPrinterList()SLGetPrinterInfo()SLGetDefPrinterName()SLGetPrinterSettings()LEFT="250" WIDTH="146"Get the list of registered printersReturn information about a printer.Get the name of the default printer.Get spooler and printer settings.LEFT="0" WIDTH="112"Option ManagementLEFT="120" WIDTH="123"SLSysVGetSpoolerOptions()SLSysVGetPrinterOptions()SLSysVSaveSpoolerOptions()SLSysVSavePrinterOptions()LEFT="250" WIDTH="146"Get System V spooler options.Get System V printer options.Save System V spooler options.Save System V printer options.LEFT="0" WIDTH="112"Print Job SubmissionLEFT="120" WIDTH="123"SLSubmitJob()SLSubmitJobFd()SLSubmitJobBuf()SLSubmitJobSimple()LEFT="250" WIDTH="146"Submit a job for printing.Submit the contents of the file
specified by a file descriptor.Submit contents of specified buffer.Submit a print job using default
values for all printing options.LEFT="0" WIDTH="112"Print Job CancellationLEFT="120" WIDTH="123"SLCancelJob()LEFT="250" WIDTH="146"Cancel a queued printer job.LEFT="0" WIDTH="112"Printer Queue InformationLEFT="120" WIDTH="123"SLGetQueue()LEFT="250" WIDTH="146"Report the printer queue contents.LEFT="0" WIDTH="112"Printer Queue ControlLEFT="120" WIDTH="123"SLSetSpoolerState()SLGetSpoolerState()LEFT="250" WIDTH="146"Set the spooling system printing
and queueing state.Get the spooling system printing
and queueing state.LEFT="0" WIDTH="112"Execution Error HandlingLEFT="120" WIDTH="123"SLPerror()SLErrorString()SLGetSpoolerError()LEFT="250" WIDTH="146"Print a libspool execution error
message to standard error.Get a libspool execution error msg.Get spooling system error info.LBL="" HELPID=""ID="45357"The libprintui LibraryID="chap68"The libprintui library implements a graphical user interface (GUI) for printing. The library provides PrintBox, a complete solution for print-job submission, to application developers. A widget that is compatible with Motif, PrintBox eliminates the need to create custom printing solutions for each application. This widget saves application developers time and effort, and makes it easier for them to provide a robust, complete printing interface.Using the PrintBox widget in an application benefits the end user in several ways. First, PrintBox provides a consistent interface to the printer spooling system across the varied applications on Silicon Graphics systems. Second, users can set print job options, such as number of copies, through a graphical interface, rather than through obscure command-line option flags. Finally, PrintBox uses the printer graphical options panel to provide a mechanism for the setting and saving of printer-specific options.The PrintBox widget can be used in a number of different configurations and can accept a child manager widget to allow the display of application-specific options. The widget provides built-in System V print job submission via the libspool library. (See IDREF="65070" TYPE="TITLE""The libspool Library" for more information.) The developer can also perform application-specific processing before a job is submitted to the printing system. A variety of callback lists provide user and spooling system feedback. A print job can be submitted as a filename, as a file descriptor, or as a pointer to the buffer. The default form of PrintBox includes the following items:A print file entry text field (for file-based jobs)A scrolling list of available printersPrint option controlsThe following action-area push buttons:PrintSubmits the specified file or buffer for printing by the spooling system.More Options name='hellip' font=symbol charset=fontspecific code=188Accesses the graphical options panel for the currently selected printer.Save Options name='hellip' font=symbol charset=fontspecific code=188Saves printer and spooling system options.CancelNormally used to pop down the PrintBox widget when the widget is used as a pop-up dialog.HelpCalls the functions on the helpCallback list.There are also four unmanaged buttons, User1 through User4, positioned between the Print and More Optionsname='hellip' font=symbol charset=fontspecific code=188 buttons These buttons, invisible by default, become visible when explicitly managed by your application. The PrintBox widget also accepts one child process as a work area. This area can be used for application-specific printing controls such as page range.LBL="" HELPID=""Example Widget ConfigurationsID="chap69"ID="chap610"IDREF="33407" TYPE="GRAPHIC"Figure 6-1 through IDREF="12639" TYPE="GRAPHIC"Figure 6-4 illustrate four widget configurations:the default configurationwithout a filename entry boxwithout an options boxwith a child processFILE="fig6-1.gif" POSITION="INLINE" SCALE="FALSE"LBL="6-1"Figure 6-1 ID="33407"PrintBox Widget: Default ConfigurationFILE="fig6-2.gif" POSITION="INLINE" SCALE="FALSE"LBL="6-2"Figure 6-2 ID="69248"PrintBox Widget: No Filename Entry BoxFILE="fig6-3.gif" POSITION="INLINE" SCALE="FALSE"LBL="6-3"Figure 6-3 PrintBox Widget: No Options BoxFILE="fig6-4.gif" POSITION="INLINE" SCALE="FALSE"LBL="6-4"Figure 6-4 ID="12639"PrintBox Widget: With a Child ProcessLBL="" HELPID=""Compiling Programs With libprintuiID="chap611"Programs that call the libprintui functions must include the header file /usr/include/Sgm/PrintBox.h and must link with the following libraries in the order shown:... -lprintui -lspool -lXm -lXt -lXll -lgen ...The link order is important for proper link-time name resolution.NotePrograms that subclass from the PrintBox widget must also include /usr/include/Sgm/PrintBoxP.h.LBL="" HELPID=""Library Functions Listed by PurposeID="chap612"The libprintui functions are listed in IDREF="53403" TYPE="TABLE"Table 6-2. The PuiPrintBox(3X) reference pages provide detailed information on the PrintBox widget.ID="chap613"COLUMNS="3"LBL="6-2"Table 6-2 ID="53403"Summary of libprintui FunctionsID="chap614"LEFT="0" WIDTH="117"TaskLEFT="125" WIDTH="97"FunctionLEFT="230" WIDTH="156"PurposeLEFT="0" WIDTH="117"Widget InstantiationLEFT="125" WIDTH="97"PuiCreatePrintBox()PuiCreatePrintDialog()LEFT="230" WIDTH="156"Create a PrintBox widget.Create a PrintBox dialog.LEFT="0" WIDTH="117"Widget Component AccessLEFT="125" WIDTH="97"PuiPrintBoxGetChild()LEFT="230" WIDTH="156"Access a PrintBox widget component.LEFT="0" WIDTH="117"Widget Action FunctionsLEFT="125" WIDTH="97"PuiPrintBoxDoPrint()LEFT="230" WIDTH="156"Invoke PrintBox printing.LBL="" HELPID=""Example ProgramID="chap615"ID="chap616"The example program, printbox, instantiates a simple PrintBox widget. The directory /usr/impressario/src/examples/libprintui contains the source code for this program, while the directory /usr/impressario/bin/examples/libprintui contains the executable version. To invoke the example program, enter:printboxLBL="" HELPID=""Initial Program ProcessingThe printbox program begins by setting the program instance name and initializing an X Window Systemname='trade' font=symbol charset=fontspecific code=228
descr='[trade]' connection. Next, the program creates the PrintBox widget with a call to the libprintui library function PuiCreatePrintBox() and adds the widget to the parent's managed set.ID="chap617"LBL="" HELPID=""Add CallbacksID="chap618"The program now adds the following callbacks:the Cancel button exit routinea help dialog displaya routine to print job information and the job ID to standard output and terminate the programa display of error messages from the PrintBox widget (this uses the function SLGetSpoolerError() from the libspool library)LBL="" HELPID=""Realize All WidgetsA call to XtRealizeWidget() now realizes (creates a window for) the parent widget, created by the earlier call to PuiCreatePrintBox(), and all child widgets.LBL="" HELPID=""Process EventsThe program now begins an event loop. It obtains the next event from the X event queue and dispatches the event. If an early error has occurred, the error is handled and the loop continues until the application exits.LBL="" HELPID=""Additional ExamplesRefer to the directory /usr/impressario/src/examples/libprintui for additional sample program source code.LBL="" HELPID=""ID="65271"The libpod LibraryID="chap619"The libpod library provides printer driver developers with an API to create and maintain a printer object database (POD) and provides application developers with the means to acquire detailed information about a printer, even across the network. A POD contains information on the current printer configuration, status, and job history of a single printer. Each printer driver installed on a system maintains its own POD on that system. All interaction with a printer's POD must be done through the libpod API. Do not modify the POD files directly. To create an initial set of POD files, refer to IDREF="64689" TYPE="TITLE"Appendix C, "Printer Object Database (POD) File Formats," and the examples provided in /usr/impressario/src/data.LBL="" HELPID=""POD FilesID="chap620"A POD consists of three separate ASCII text files. The name of each POD file is formed from the printer name, followed by one of these suffixes: .config, .status, or .log. The name and contents of each file are as follows:COLUMNS="2"LEFT="0" WIDTH="99"[printer_name].configID="chap621"ID="chap622"LEFT="105" WIDTH="234"The configuration file contains detailed information
on the printer's capabilities. Examples include the
supported paper sizes and available fonts. The
initial version of this file is manually created by the
printer driver developer, and a copy is installed
when the printer is added to the system. The
contents of this file are maintained by the system
administrator using the printer administration
tools. Normally this file is never changed.LEFT="0" WIDTH="99"[printer_name].statusID="chap623"ID="chap624"LEFT="105" WIDTH="234"The status file contains information about the
current operational status of the printer. The
information in this file indicates whether the printer
is busy, the type of printing media installed, detailed
error codes (if errors have occurred), and so on. The
contents of this file change during the course of
every print job.LEFT="0" WIDTH="99"[printer_name].logLEFT="105" WIDTH="234"The log file contains the print job history for the
printer. Information for old jobs as well as the
current print job is maintained. Typically, printer
filters and drivers append information to the log file
while general applications treat the file as read-only.The global variable PDpod_path indicates the location of the POD files. The default location for the POD files is /var/spool/lp/pod. If the POD files are to be located in a directory other than the default, set PDpod_path to the path name of the new location. PDpod_path is declared in the header file pod.h.The maximum string length for PDpod_path is PD_STR_MAX. This length includes the terminating NULL character.ID="chap625"See IDREF="64689" TYPE="TITLE"Appendix C, "Printer Object Database (POD) File Formats," for detailed information on libpod file formats.LBL="" HELPID=""Standard and Local libpod FunctionsID="chap626"ID="chap627"The print serverID="chap628" is the system that controls the printer. The POD files reside on the print server. To provide POD information to a system other than the print server, that is, to a ID="chap629"print client, libpod must be able to communicate across the network. For any specified printer, the "standard" libpod functions automatically determine whether the user's system is the print server or a print client. After determining which system is the print server, the standard libpod functions are able to access the POD files on that system. Because they typically run on print clients, user application programs such as printer status tools use the standard form of the libpod functions.To avoid the overhead that network communication entails, libpod also provides "local" functions. These functions, such as PDLocalReadInfo() and PDLocalWriteStatus(), contain the word "Local" in their names and use the POD files on the system on which they are running, that is, the local system. Because they have no networking overhead, their use reduces the size and overhead of the resulting executable files. They are intended for programs, such as printer drivers, that are used only on print servers.Functions that write to POD files are available only in the local form. Only printer drivers write to POD files and these drivers always run locally on print servers, never remotely on print clients. Thus, there is no need to provide standard libpod functions that write to POD files.LBL="" HELPID=""Compiling Programs With libpodID="chap630"Programs that call libpod functions must include the header file pod.h, which is located in the directory /usr/include. The programs must also link with the library libpod.a located in /usr/lib. In addition, programs that use the standard libpod functions must link with libspool.a. Programs that use only the local libpod functions need not link with this additional library.The compile line for using the standard functions iscc -o myprog myprog.c -lpod -lspool The compile line for using the local functions iscc -o myprog myprog.c -lpod LBL="" HELPID=""Debugging With libpodID="chap631"If the global variable PDdebug is set to a nonzero value, libpod functions will print debugging information to standard error during execution. The global variable PDdebug is declared in the header file pod.h.LBL="" HELPID=""Network CommunicationsTo provide remote printer POD information, libpod communicates over the network with the podd daemon on the remote machine. Since the network or remote machine may be unreachable when a libpod function is executed, a time-out may occur with the function returning an appropriate error code. The time-out period can be specified by setting the global variable PDnet_timeout to a value in seconds. The default time-out period is contained in the header file pod.h. The time-out period for reading printer status is usually much larger than that for browsing printer configurations. For more specific information on the daemon, refer to the podd(1M) reference page.LBL="" HELPID=""Library Functions Listed by PurposeID="chap632"The libpod functions are listed in IDREF="47432" TYPE="TABLE"Table 6-3. Note that a number of libpod functions have only a single version, which is used for both standard and local cases.ID="chap633"COLUMNS="3"LBL="6-3"Table 6-3 ID="47432"Summary of libpod FunctionsID="chap634"LEFT="0" WIDTH="127"TaskLEFT="135" WIDTH="112"Standard FunctionLEFT="255" WIDTH="103"Local FunctionLEFT="0" WIDTH="127"Detailed Information RetrievalLEFT="135" WIDTH="112"PDReadInfo()LEFT="255" WIDTH="103"PDLocalReadInfo()PDLocalWriteInfo()LEFT="0" WIDTH="127"Status File ManipulationLEFT="135" WIDTH="112"PDReadStatus()PDReadOpStatus()LEFT="255" WIDTH="103"PDLocalReadStatus()PDLocalWriteStatus()PDLocalReadOpStatus()LEFT="0" WIDTH="127"Log File ManipulationLEFT="135" WIDTH="112"PDReadLog()LEFT="255" WIDTH="103"PDLocalReadLog()PDLocalWriteLog()LEFT="0" WIDTH="127"Convenience FunctionsLEFT="135" WIDTH="112"PDMakeMessage()PDFindPageSize()PDGetSizeCodeByName()PDGetNameBySizeCode()PDGetCurrentResolution()LEFT="255" WIDTH="103"n/an/an/an/an/an/aLEFT="0" WIDTH="127"Execution Error HandlingLEFT="135" WIDTH="112"PDError()PDErrorString()LEFT="255" WIDTH="103"n/an/aLBL="7"ID="64426"Scanner DriversID="chap71"This chapter discusses scanner driver development. It provides a detailed analysis of the template scanner driver.The following major topics are discussed in this chapter:IDREF="34736" TYPE="TITLE""Driver Template"IDREF="28616" TYPE="TITLE""Header Files"IDREF="28735" TYPE="TITLE""Data Structures"IDREF="53681" TYPE="TITLE""Functions You Must Write"IDREF="58073" TYPE="TITLE""Events"IDREF="32296" TYPE="TITLE""Installation"IDREF="35714" TYPE="TITLE""Testing"The information presented in this chapter should be enough to write a scanner driver. However, if you wish to know more, IDREF="36071" TYPE="TITLE"Appendix E, "Scanner Driver Architecture," is an in-depth discussion of the architecture of a scanner driver.LBL="" HELPID=""ID="34736"Driver TemplateThe source code files for the template scanner driver are in the directory /usr/impressario/src/scan/template_driver. This template has code to handle all the interprocess communication necessary for well-behaved scanner drivers (see IDREF="59965" TYPE="TITLE"Chapter 9, "Generic Scanner Interface").To develop a new scanner driver, start by copying the template files to the directory where you will be developing the driver. The only files that you need to modify are scan.c and Makefile; Donot modify any of the other files unless you are familiar with the information in IDREF="36071" TYPE="TITLE"Appendix E.This document refers to the main.c module, which implements the interprocess communication part of a scanner driver and should not be modified; and scan.c, which you should modify to support the scanner for which you are writing a driver.LBL="" HELPID=""ID="28616"Header FilesID="chap72"ID="chap73"ID="chap74"ID="chap75"ID="chap76"ID="chap77"There are four header files in /usr/include that are useful to scanner driver developers:scanner.hID="chap78"Defines the interface used by application programmers to communicate with scanner drivers. Contains typedef and #define definitions needed to communicate with the application.scandrv.hID="chap79"Contains the dispatch loop interface, some error messages, and the queue utility routines.scanipc.hID="chap710"Contains #define definitions for command numbers and the types of arguments and results.scanconv.hID="chap711"Contains prototypes for functions that convert between data types and functions that do replicative zooming on rows of image data.LBL="" HELPID=""ID="28735"Data StructuresThe following data structures are used to communicate between scanner driver template modules. Understanding each field is key to understanding what your part of the driver (the code in scan.c) must do. These data structures are defined in /usr/impressario/src/scan/template_driver/scan.h.LBL="" HELPID=""SCANINFO Data StructureID="chap712"ID="chap713"The SCANINFO data structure is used to store static information about a scanner. The scan.c module uses SCANINFO to communicate with the main.c module. The SCANINFO data structure is defined as follows:typedef struct tag_scaninfo {
} SCANINFO;Field definitions:metricSet metric to SC_INCHES or SC_CENTIM, depending on whether it is more convenient to have measurements and resolutions expressed in terms of inches or centimeters.pagex, pagey, pagewidth, pageheightpagex and pagey are the coordinates of the upper left corner of the scannable area (almost always 0 and 0). pagewidth and pageheight are the width and height of the scannable area, respectively. All four fields are expressed in the units defined by the metric field.minxres, maxxres, minyres, maxyresminxres is the smallest supported horizontal resolution, maxxres is the largest supported horizontal resolution, minyres is the smallest supported vertical resolution, and maxyres is the largest supported vertical resolution. These are all expressed in pixels per the unit expressed by the metric field.xres, yres, nresFor scanners that support discrete resolutions (as opposed to scanners that support all resolutions with equal quality, within the bounds given above), xres and yres are arrays of the supported resolutions in the horizontal and vertical directions. nres is the number of elements in each of these arrays.For scanners that support arbitrary resolutions (that is, scanners that do their own scaling), nres is 0. The main.c module takes nres equal to 0 to signify that it doesn't need to do any scaling of scan data to satisfy preview requests from the scanning application.canZoomThis parameter specifies whether or not the scanner can support resolutions other than those specified in the xres and yres arrays when nres is nonzero. In this case, the resolutions in the xres and yres arrays represent preferred resolutions that results in superior image quality.If nres is 0, the main.c module assumes that the scanner itself can do zooming, regardless of the canZoom flag.types, ntypestypes is an array of SCDATATYPE structures (see IDREF="59965" TYPE="TITLE"Chapter 9, "Generic Scanner Interface"), and ntypes is the number of types supported by the scanner.options, noptionsThis array of functions implements scanner-specific options for this scanner (see IDREF="87965" TYPE="TITLE"Chapter 8, "Scanner-Specific Options"), and noptions is the number of such options.privThis parameter is used by the scan.c module (the one you write) to store a pointer to whatever state information is necessary to identify a particular scanner once it's been opened. This is provided so that you can avoid the use of global variables in the scan.c module.feederFlagsThese flags indicate the presence of an automatic document feeder. The SC_HASFEEDER bit (see /usr/include/scanner.h) of this flag should be set if a feeder is attached to the scanner being supported. The SC_AUTOFEED flag should be set if each call to DoScan() automatically results in the next sheet of paper being fed. If the scanner can feed on demand, the SC_PROGFEED bit should be set. It is not an error to have the SC_AUTOFEED flag and the SC_PROGFEED flag both set.If the scanner being supported does not have a document feeder, this member can be safely ignored and the main.c module will not try to call any of the document feeder functions (see below).LBL="" HELPID=""SCANPARAMS Data StructureID="chap714"ID="chap715"The SCANPARAMS data structure contains dynamic values used to specify the parameters of a scanning operation, and also some administrative details. The SCANPARAMS data structure is defined as follows:typedef struct tag_scanparams {
float xres, yres;
float x, y, width, height;
SCDATATYPE type;
int preview;
SCQUEUE *scanq, *sfreeq;
int xpixels, ylines, xbytes;
void (*convert)(void *from, int fromx, void *to, int tox, int *zmap);
int maxmem; /* maximum amount of memory to allocate */
int readlines;
SCANINFO *s;
} SCANPARAMS;The fields of the SCANPARAMS data structure are defined as follows:xres, yresThe scanning resolution to be used for a particular scan. The main.c module always ensures that these resolutions are among those advertised in the xres and yres fields of the SCANINFO struct, unless the canZoom field of the SCANINFO struct is nonzero or the nres field is 0. In any case, xres and yresare always within the resolution bounds specified in the SCANINFO struct.xres and yres are expressed in dots per the unit specified in the metric field of the SCANINFO struct.x, y, width, heightThe horizontal (x) and vertical (y) coordinates of the upper left corner of the window to be scanned and its width and height. The main.c module ensures that this image falls within the bounds of the pagex, pagey, pagewidth, and pageheight fields of the SCANINFO struct.x, y, width, and height are expressed in the units specified in the metric field of the SCANINFO struct.typeThe type of scan data expected. The main.c module ensures that it is one of the types specified in the types field of the SCANINFO struct.previewThis field is set to 1 if this is a preview scan, and 0 otherwise.scanq, sfreeqsfreeq is a queue whose elements are free buffers to put scanned data into, and scanq is a queue whose elements are buffers that have scanned data in them. DoScan(), which you write (see below), removes buffers from sfreeq, scans the data into them, then adds them to scanq. The main.c module is responsible for taking buffers from scanq, disposing of the data appropriately, and putting them back on sfreeq.xpixels, ylines, xbytesThe number of pixels in a scan line, the number of scan lines in the scan, and the number of bytes in a scan line. The scan.c module is responsible for calculating these values in SetupScan(), which you write (see below).void (*convert)(void *from, int fromx, void *to, int tox, int *zmap)This function converts data from a type that the scanner supports to the requested data type. If the scanner directly supports all the data types that are being advertised to the scanning application (the types field of the SCANINFO struct), the scan.c module can ignore this field.For example, this function can be used for color scanners that return the red, green, and blue components of each scan line separately; that is, a line of five pixels would have the following layout:RRRRRGGGGGBBBBBThis needs to be converted to chunky data, as shown below:RGBRGBRGBRGBRGBTo do this, simply set the convert field to SCBandRGB8ToPixelRGB8 in SetupScan() (see below). The following functions are available in libscan for converting:SCBandRGB8ToPixelRGB8()SCGrey8ToMono()SCBandRGB8ToMono()maxmemThe maximum amount of memory that should be allocated for storing scan data. This field is to be taken into account in the calculation of readlines in SetupScan() (see below).readlinesThe number of lines to read at a time. readlines is the maxmem field divided by the xbytes field if scanning is benefited by scanning in large chunks. If there is no benefit, the number is 1.The problem with maxmem/xbytes is that when maxmem is large, interactive feedback to the user of the scanning application is limited. Ideally, the scanner buffers data internally, so you can scan perhaps an inch at a time without the scan head pausing. That way, the scanning application can consume the scan data while the scan head gets the rest of the data.sA pointer to the SCANINFO struct that OpenScanner() returned (see below).LBL="" HELPID=""ID="53681"Functions You Must WriteAfter copying the template to your build area, you must edit the file scan.c and implement the functions listed in IDREF="85703" TYPE="TABLE"Table 7-1.These functions are described in detail in the following sections.COLUMNS="2"LBL="7-1"Table 7-1 ID="85703"Functions to Be Written by the Driver DeveloperLEFT="0" WIDTH="74"Function NameLEFT="80" WIDTH="261"DescriptionLEFT="0" WIDTH="74"OpenScanner()LEFT="80" WIDTH="261"Opens the scannerLEFT="0" WIDTH="74"SetupScan()LEFT="80" WIDTH="261"Called before a scanning operationLEFT="0" WIDTH="74"DoScan()LEFT="80" WIDTH="261"Gets data from the scannerLEFT="0" WIDTH="74"SetFeederFlags()LEFT="80" WIDTH="261"Called when the scanner application calls SCFeederSetFlagsLEFT="0" WIDTH="74"AdvanceFeeder()LEFT="80" WIDTH="261"Advances feeder to next documentLEFT="0" WIDTH="74"FeederReady()LEFT="80" WIDTH="261"Tests whether the feeder is ready to feed another documentLEFT="0" WIDTH="74"PrintID()LEFT="80" WIDTH="261"Prints a string describing the type of scanning supportedLEFT="0" WIDTH="74"FindScanners()LEFT="80" WIDTH="261"Prints device for supported scannersLEFT="0" WIDTH="74"InstallScanner()LEFT="80" WIDTH="261"Installs a new scannerLEFT="0" WIDTH="74"DeleteScanner()LEFT="80" WIDTH="261"Deletes a scannerLBL="" HELPID=""OpenScanner() FunctionID="chap716"ID="chap717"This function is called when the driver is first invoked.For example:SCANINFO *
OpenScanner(char *dev)
{
static SCANINFO scan;
/*
Your code here!
*/
if (something goes wrong) {
drverr = appropriate error code;
return NULL;
}
*/
return &scan;
}dev is the name of the device (usually a device special file in /dev/scsi for SCSI devices) to open in order to communicate with the scanner. The task of the OpenScanner() function is to "open" dev, make sure that it corresponds to a device that scan.c knows how to talk to, get it into some reasonable initial state, and fill in a SCANINFO structure for the scanner. If all goes well, a pointer to the SCANINFO structure is returned.If anything goes wrong, OpenScanner() should set the global variable drverr and return NULL. The value for drverr should be chosen from those in /usr/include/sys/errno.h or /usr/include/scanner.h; that value is communicated back to the scanning application, which can use the SCPerror() or SCErrorString() functions in libscan.a to get a human-readable error message that explains why OpenScanner() failed.CautionIf you are writing a driver for a SCSI scanner, and you are using dslib(3X), make sure that you pass the O_EXCL flag defined in /usr/include/fcntl.h to dsopen:dsreq_t *dsp = dsopen(dev, O_RDONLY | O_EXCL);If you pass the O_EXCL flag, the open will fail with errno set to EBUSY if dev is the /dev/scsi device of a mounted disk; otherwise, the open can succeed and you could really screw up the disk!In addition, it is recommended that before issuing any other SCSI commands you perform an inquiry command, and verify that the device is a scanner by examining the Device Type code of the inquiry buffer. (This field should be set to 6. You can use the INV_SCANNER #define from /usr/include/invent.h.) It is also recommended that you examine the vendor and product identifiers to make sure the device is a scanner of the type for which this driver is being written.LBL="" HELPID=""SetupScan() FunctionID="chap718"ID="chap719"This function is called with a pointer to a SCANPARAMS struct to prepare for a scanning operation.For example:int
SetupScan(SCANPARAMS *params)
{
/*
Your code to tell the scanner the resolution, scanning window,
and data type.
*/
/*
Your code to find out from the scanner how many pixels are in a scan
line, how many scan lines are in the scan, and how many bytes are
in a scan line.
*/
/*
Your code to figure out what readlines should be, taking into
consideration maxmem and xbytes.
*/
if (anything went wrong) {
drverr = an appropriate error code;
return -1; /* indicates failure */
}
return 0; /* indicates success */
}
SetupScan() performs the following operations:SetupScan() does whatever is necessary to anticipate the scan defined by the fields xres, yres, x, y, width, height, and type.If type is not supported directly by the scanning device, then the convert field should be set to a function that converts data returned from the scanner to the appropriate type.SetupScan() queries the scanning device or does some calculations to determine the number of pixels in a scan line, the number of scan lines in the scan, and the number of bytes in a scan line. The xpixels, ylines, and xbytes fields of params are set appropriately.SetupScan() sets the readlines field of params to the number of lines that it expects to scan at a time, taking maxmem and xbytes into account.If at any point something goes wrong, set drverr to a value from /usr/include/sys/errno.h or /usr/include/scanner.h and return -1 to indicate a failure. If all goes well, return 0 to indicate success.LBL="" HELPID=""DoScan() FunctionID="chap720"ID="chap721"This function retrieves the data from the scanner.For example:void
DoScan(SCANPARAMS *params)
{
SCANINFO *s = params->s;
void *buf;
int row, toread, curline;
prctl(PR_TERMCHILD);
for (curline = 0; curline < params->ylines;
curline += params->readlines) {
toread = MIN(params->readlines,
params->ylines - curline);
buf = SCDequeue(params->sfreeq);
/*
* Get the scan data here!
*/
/*
* Chop the buffer up into scan line sized chunks
*/
while (toread--) {
SCEnqueue(params->scanq, buf);
buf = (char *)buf + params->xbytes;
}
}
exit(0);
}DoScan() executes as its own process, sharing its address space with its parent, which is the process that communicates with the scanning application. (See the sproc(2) reference page. DoScan() is the entry parameter to sproc.)Before entering the while loop, do whatever else is necessary to initialize the scanner if there's unfinished business from SetupScan(). Note the use of params->readlines, which you set in SetupScan(). In the body of the loop, the following things happen:DoScan() computes how many scan lines to read this time through the loop. This is either readlines, which was set in SetupScan(), or the number of lines remaining to scan:toread = MIN(params->readlines, params->ylines - curline);DoScan() gets a buffer from the free queue into which the data is scanned:buf = SCDequeue(params->sfreeq);DoScan() transfers toread lines of data from the scanning device to buf. This is the interesting part, that you have to write specifically for your scanner.DoScan() puts the lines just scanned onto the scan queue. This involves chopping up the buffer into chunks the size of a scan line. Don't worry, main.c knows how to put the buffers back together before putting them back on the free queue!while (toread--) {
SCEnqueue(params->scanq, buf);
buf = (char *)buf + params->xbytes;
}Since DoScan() is its own process, it calls the exit function instead of returning when it finishes scanning. If everything goes OK, DoScan() calls exit with a status of 0. If anything goes wrong, DoScan() sets the global variable drverr to an appropriate value from sys/errno.h or scanner.h and calls exit with a status of 1. (See the exit(2) reference page.)LBL="" HELPID=""SetFeederFlags() FunctionID="chap722"ID="chap723"The SetFeederFlags() function is called when the scanner application calls SCFeederSetFlags to specify whether automatic (SC_AUTOFEED) or programmatic (SC_PROGFEED) feeding is desired. This only happens if the feederFlags member of the SCANINFO struct returned by OpenScanner() has all three of the SC_HASFEEDER, SC_AUTOFEED, and SC_PROGFEED bits set.For example:int
}The template version of this function sets drverr to indicate that no feeder is present; if a feeder is present, SetFeederFlags() must set a flag so that it knows whether to automatically feed the next document in the next call to DoScan().LBL="" HELPID=""AdvanceFeeder() FunctionID="chap724"ID="chap725"The AdvanceFeeder() function is called only if the SC_PROGFEED bit is set in the feederFlags member of the SCANINFO struct returned by OpenScanner(). This function should advance the feeder to the next document. If the feeder is empty or jammed, return -1 and set drverr to an appropriate error code from /usr/include/scanner.h or /usr/include/sys/errno.h.For example:int
AdvanceFeeder(SCANINFO *scan)
{
drverr = SCENOFEEDER;
return -1;
}LBL="" HELPID=""FeederReady() FunctionID="chap726"ID="chap727"This function is called only if the SC_HASFEEDER bit of the feederFlags field of the SCANINFO struct returned by OpenScanner() is set.For example:int
FeederReady(SCANINFO *scan)
{
drverr = SCENOFEEDER;
return -1;
}FeederReady() should return 0 if there is a document in the feeder; that is, if the next call to AdvanceFeeder() should succeed. If the feeder is empty, FeederReady() should return -1 and set drverr to SCFEEDEREMPTY.LBL="" HELPID=""PrintID() FunctionID="chap728"ID="chap729"The PrintID() function is used by the -query option that all scanner drivers support. It should print a string that identifies the type of scanner supported by this scanner driver, and one or more interface types supported. The scanner install tool, scanners, uses this information to help the end user choose the driver that best suits a particular scanner.For example:void
fprintf(fp, "SCSI Serial Parallel\n"); /* Device type; can be list */
}LBL="" HELPID=""FindScanners() FunctionID="chap730"ID="chap731"The FindScanners() function is also used to implement the -query option.For example:void
FindScanners(FILE *fp)
{
inventory_t *inv;
char device[100];
dsreq_t *dsp;
/* int because it must be word aligned. */
int inqbuf[(sizeof(INQDATA) + 3)/sizeof(int)];
INQDATA *inq = (INQDATA *)inqbuf;
/*
* This example looks for SCSI scanners; do whatever is necessary
* to find other types of scanner here.
*/
setinvent();
while ((inv = getinvent()) != NULL) {
if (inv->inv_class == INV_SCSI && inv->inv_type == INV_SCANNER) {
FindScanners() should search the system for scanners that this driver is capable of supporting, and for each such scanner it prints the type of device (SCSI, Serial, Parallel, GPIB, EISA, or Other), a space, and the pathname that should be passed to OpenScanner() in order to access that scanner.This gives scanners more information that it can use to help the end user pick a driver for a particular scanner. It is by no means required that FindScanners() find all scanners that it is capable of supporting; it is OK to do nothing at all here, especially if there is no hope of finding a scanner you support in a reasonable amount of time. This is important; scanners invokes EVERY scanner driver installed with the -query option when the user adds a scanner, so this function should be fast!LBL="" HELPID=""InstallScanner() FunctionID="chap732"ID="chap733"This function is called when the scanner driver is invoked with the -install option. InstallScanner() is used by scanners when the user tries to install a new scanner. For example:int
InstallScanner(char *dev)
{
printf("The template driver doesn't support %s\n", dev);
return -1;
}The purpose of this entry point is verify that dev corresponds to a scanning device that this driver knows how to support, and to do any scanner-specific installation that is necessary.The following example implementation calls OpenScanner() to verify that dev corresponds to a valid scanning device, and then changes the permissions of dev so that users other than root can access the scanner. This is important, because scanner drivers should not normally be set to user ID root programs, and users other than root want to use scanners. When InstallScanner() is called by scanners, the driver will have root permissions, which enables it to call chmod(2) on dev or create any auxiliary files or other resources that it needs:int
}If an error occurs, InstallScanner() should print an error message to standard out and return -1. The main.c module exits with a nonzero exit status if InstallScanner() returns -1, and scanners reads the driver's standard output and displays it to the user if the main.c exits with a nonzero status. That way, the exact cause of the error is propagated to the user.LBL="" HELPID=""DeleteScanner() FunctionID="chap734"ID="chap735"The DeleteScanner() function is called when the driver is invoked with the -delete option by scanners. This gives the driver the opportunity to do any scanner-specific deletion required. This can be useful if auxiliary files specific to this scanner were created in InstallScanner().For example:int
DeleteScanner(char *dev)
{
return 0;
}
If an error occurs, DeleteScanner() prints an error message to standard out and returns -1. In this case, scanners displays this error message to the user and refuses to delete the scanner, so in most cases DeleteScanner() should return 0.LBL="" HELPID=""ID="58073"EventsID="chap736"Impressario scanner drivers can send events to scanner applications. Currently, the only type of event supported is an event to notify the scanner application that the resolutions, page size, data types, or feeder flags supported by the scanner driver have changed.This typically happens when the user selects a new input media option from the scanner specific options program (see chapter 8). For example, some scanners have transparency units, and when scanning transparencies the scanning page size is different than when scanning normal paper. So when the user selects the option to scan a transparency, the scanner driver needs to inform the scanning application that it must query to find out the new page size.Events are sent to the scanner application by filling in an SCEVENT structure and calling SCDriverSendEvent(). The SCEVENT structure is defined as follows:typedef struct tag_infoChange {
unsigned int pageSizeChanged : 1;
unsigned int resolutionChanged : 1;
unsigned int dataTypesChanged : 1;
unsigned int feederFlagsChanged : 1;
} SCINFOCHANGE;
#define SCEVENT_INFOCHANGE 1
typedef struct tag_scevent {
unsigned int eventType;
union {
SCINFOCHANGE infoChange;
event;
} SCEVENT;The SCDriverSendEvent() function has the following prototype:int SCDriverSendEvent(SCEVENT *event)To inform the scanner application that it needs to query the new page size, the driver executes the following code:SCEVENT event;
event.eventType = SCEVENT_INFOCHANGE;
event.event.infoChange.pageSizeChanged = 1;
event.event.infoChange.resolutionChanged = 0;
event.event.infoChange.dataTypesChanged = 0;
event.event.infoChange.feederFlagsChanged = 0;
if (SCDriverSendEvent(&event) == -1) {
handle error;
}LBL="" HELPID=""ID="32296"InstallationID="chap737"After the driver is built, make sure that the -query option works, then copy it to /usr/lib/scan/drv and run scanners, the scanner install tool. See IDREF="24128" TYPE="GRAPHIC"Figure 7-1.FILE="fig7-1.gif" POSITION="INLINE" SCALE="FALSE"LBL="7-1"Figure 7-1 ID="24128"Scanner Install ToolWhen the scanners panel comes up, use the "Install..." item on the Scanner menu to bring up the "Install New Scanner" dialog box. If you implemented PrintID() correctly, you see your scanner driver's ID string in the list. If you implemented FindScanners(), clicking on your scanner driver type should fill in the "Device" field. Otherwise, type in the device that corresponds to your scanner.LBL="" HELPID=""ID="35714"TestingGive the scanner a name and click OK, then run gscan. See IDREF="20674" TYPE="GRAPHIC"Figure 7-2.FILE="fig7-2.gif" POSITION="INLINE" SCALE="FALSE"LBL="7-2"Figure 7-2 ID="20674"gscan PanelYou can either provide your scanner's name on the command line or use the Setup menu to choose your scanner as the scanning source.Severe scanner driver malfunctions can cause gscan to hang. If this happens, open a shell and enter:/etc/killall gscanLBL="8"ID="87965"Scanner-Specific OptionsID="chap81"This chapter describes the implementation of scanner-specific graphical options panels.The following major topics are discussed in this chapter:IDREF="71619" TYPE="TITLE""Options Program and the Scanner Driver Interface"IDREF="72535" TYPE="TITLE""Scanner Driver's Perspective"IDREF="12254" TYPE="TITLE""Options Program's Perspective"IDREF="11168" TYPE="TITLE""Installation and Testing"LBL="" HELPID=""OverviewMost scanners have capabilities that would not be available to application programs through the generic scanner API alone. A scanner-specific graphical options panel program can be developed to provide access to these capabilities.ID="chap82"A scanner-specific options program is run by a scanner application and communicates directly with a scanner driver, bypassing the generic scanner API. It should provide user interface elements (using Motif or a similar toolkit) for the scanner features it supports that are not supported by the generic scanner API. It should also communicate appropriate settings to the scanner driver.The scanner driver, in turn, must respond to commands from its corresponding scanner-specific options program.LBL="" HELPID=""ID="71619"Options Program and the Scanner Driver InterfaceID="chap83"The options program executes driver commands by writing a command number and the arguments to that command onto a pipe. The scanner driver reads the command and arguments from the pipe, then calls the options function for that command. After the options function returns, the driver writes the results of the function back to the options program.ID="chap84"Developers of new scanner drivers and options programs need not worry about the low-level communication between these programs; this is all taken care of in libscan.a. They do need to ensure that the scanner drivers and options programs interpret commands and arguments consistently. This is most easily accomplished by providing a common header file that the driver and the scanner options program share. This header file should contain #defines for the scanner-specific commands and typedefs for the arguments, and return values of these commands. ID="chap85"sclopt.h, for example, is included by both the HP ScanJet scanner driver and the HP ScanJet options panel:/*
* sclopt.h
* Stuff for scl scanner-specific options
*/
#define SCL_GETOPTS (SCN_SCANSPECIFIC + 0)
#define SCL_SETOPTS (SCN_SCANSPECIFIC + 1)
#define DITH_COURSE 0
#define DITH_FINE 1
#define DITH_BAYER 2
#define DITH_VERTICAL 3
typedef struct tag_sclopt {
int intensity; /* Intensity of image */
int minIntensity, maxIntensity; /* Intensity bounds; used */
/* in GETOPTS only */
int contrast; /* Image contrast */
int minContrast, maxContrast; /* Contrast bounds; used */
/* in GETOPTS only */
int bwDither; /* if nonzero, dither */
/* black and white data */
int bwDitherPattern; /* specify black & white */
/* dither pattern */
} SCLOPT;sclopt.h defines two HP ScanJet-specific commands: SCL_GETOPTS and SCL_SETOPTS. Scanner-specific commands must be numbered consecutively, starting with SCN_SCANSPECIFIC and increasing monotonically from there. SCN_SCANSPECIFIC is defined in /usr/include/scanipc.h.The ID="chap86"SCLOPT structure is used to pass information between the HP ScanJet scanner driver and the HP ScanJet options panel. This structure is the return type of the SCL_GETOPTS command and the argument type of the SCL_SETOPTS command.IDREF="72535" TYPE="TITLE""Scanner Driver's Perspective" below describes how the scanner driver uses these #defines and typedefs. IDREF="12254" TYPE="TITLE""Options Program's Perspective" describes how the scanner-specific options program uses them.LBL="" HELPID=""ID="72535"Scanner Driver's PerspectiveThe scanner driver implements scanner-specific options by providing a table of functions to the main.c module. In ID="chap87"OpenScanner(), the scan.c module should set the options field of the SCANINFO struct to an array of functions implementing the scanner-specific options, and the noptions field to the number of such options. The order of the functions in the options table must correspond to the numerical order of the commands implemented (the cmd argument, below).Each function in this array must have the following prototype:void optionfunc(int cmd, SCARG *arg, SCRES *res);cmd is the command number for this scanner-specific option. SCARG is defined in the file /usr/include/scandrv.h as follows:typedef struct tag_scarg {
void *data;
int len;
} SCARG;arg->data points to the arguments passed in by the scanner-specific options program, and arg->len is the number of bytes pointed to by arg->data.SCRES is defined in the file /usr/include/scandrv.h as follows:typedef struct tag_scres {
void *data;
int len;
void *freeparam;
void (*free)(void *param, void *data);
int errno;
char *errmsg;
} SCRES;res->data should be set to point to the results of the scanner-specific option, and res->len should be set to point to the number of bytes in res->data. If an error occurs, res->errno should be set to one of the values from sys/errno.h or scanner.h. If res->free is nonzero, it is called with res->freeparam as its first argument and res->data as its second argument, after res->data has been transferred to the scanner-specific options program. This can be used to free memory that was dynamically allocated to temporarily hold the results.For example, here is the code from the ScanJet driver that implements the HP ScanJet options:static SCLOPT scanOptions;
static void
GetOptions(int cmd, SCARG *arg, SCRES *res)
{
res->data = &scanOptions;
res->len = sizeof scanOptions;
}
static void
SetOptions(int cmd, SCARG *arg, SCRES *res)
{
scanOptions = *(SCLOPT *)arg->data;
}
SCANFUNC opttable[] = {
GetOptions,
SetOptions,
};In OpenScanner(), the options member of the SCANINFO struct is set to opttable, and the noptions member is set to 2. Note that the order of the functions in opttable corresponds to the numerical order of the commands they implement.SCANFUNC is a typedef from /usr/include/scandrv.h:typedef void (*SCANFUNC)(int cmd, SCARG *arg, SCRES *res);NoteThe actual code in the ScanJet driver is slightly more complex; error checking has been eliminated from this example code so as not to obscure the basic functionality.The SetOptions() function should verify that the options passed to it are valid and set res->errno to a value from the /usr/include/sys/errno.h directory or /usr/include/scanner.h if they are not. Also, the ScanJet function SetOptions() will fail if the scanner is currently scanning, because verifying that the options are valid would interrupt the scan. So, in this case, SetOptions() should set res->errno to SCEBUSY and return.LBL="" HELPID=""ID="12254"Options Program's PerspectiveThe scanner-specific options program is executed by ID="chap88"libscan.a when the scanner application calls the function ID="chap89"SCOptions(). The program is executed with command-line arguments that, when passed to the libscan.a function ID="chap810"SCGetScanOpt(), enable a connection to be established with the scanner driver.One of the first things that a scanner-specific options program must do, then, is call SCGetScanOpt(). This function has the following prototype (from /usr/include/scanipc.h):SCANOPT * SCGetScanOpt(int *argc, char *argv[]);The scanner-specific options program communicates with the scanner driver by making calls to the function SCScanOpt(), which has the following prototype (from /usr/include/scanipc.h):int SCScanOpt(SCANOPT *s, int cmd, void *args, int arglen, void *res, int reslen);The first argument to SCScanOpt() is the pointer returned by SCGetScanOpt(), above. The cmd argument is one of the command #defines from the common header file shared with the scanner driver. args is a pointer to the arguments to this command, and arglen is the number of bytes pointed to by args. This corresponds to arg->data and arg->len in the scanner driver option function for cmd.res points to space for receiving the results of the command, and reslen is the maximum number of bytes to copy into res. The data copied into res corresponds to res->data in the scanner driver option function for cmd.The following example code was distilled from the ScanJet options program. The ScanJet options program is a Motif program; please refer to the X and Xt Motif documentation set (see ID="chap811"IDREF="45666" TYPE="TITLE""Related Publications," in the IDREF="43783" TYPE="TITLE""About This Guide" section of this manual for the full names and order numbers) for information about the non-scanning portions of the code below.static Widget toplevel;
/* ... create widgets corresponding to options ... */
XtRealizeWidget(toplevel);
XtAppMainLoop(appContext);
return 0;
}main() calls ID="chap812"XtAppInitialize(3Xt) to initialize the X toolkit, and then calls SCGetScanOpt()ID="chap813" to get the connection to the scanner driver. Then it calls SCScanOpt()ID="chap814" to get the current options settings from the scanner driver.If anything goes wrong, main() calls a function (not shown here, but part of the ScanJet options program) called InitError(), which transforms the application into a message dialog containing the error message passed as the third argument.The ScanJet options program has an OK button that the user presses after setting up the options desired. Below is an excerpt from the callback function for that OK button.static void
}Again note the error check; PostError() is another function from the ScanJet options program, which displays a message dialog containing an error message.Also note that we call exit() if the call to SCScanOpt() succeeds. This is because the scanner options program appears to the user to be a dialog box associated with the scanning application that executed it. The ScanJet options program also provides an Apply button for changing scanner-specific settings without dismissing the scanner-specific options program.LBL="" HELPID=""ID="11168"Installation and TestingAfter you have written your scanner driver and scanner options program, copy your scanner driver to the directory /usr/lib/scan/drv, and the options program to the directory /usr/lib/scan/opt. The driver and options program must have the same base name in order for scannersID="chap815", the scanner installation tool, to recognize that they go together.Next, run scanners to install your scanner. If it was already installed before you copied your options program to /usr/lib/scan/opt, you must delete the scanner first (using the "Delete..." command on the Scanner menu).Now you can run gscan to test your driver and options program. The "Scanner Specific Options..." command on the Parameters menu should bring up your options program.LBL="9"ID="59965"Generic Scanner InterfaceID="chap91"This chapter describes the interface between a scanner driver and an application program.The following major topics are discussed in this chapter:IDREF="62698" TYPE="TITLE""Coordinate System for Scanning"IDREF="38931" TYPE="TITLE""Data Structures"IDREF="94828" TYPE="TITLE""Data Type Conventions"IDREF="84083" TYPE="TITLE""Functions"LBL="" HELPID=""OverviewThe generic interface between a scanner driver and an application program is flexible enough to accommodate a wide range of scanners and application programs. Application programs that use this interface can use any scanner that has a driver that supports this interface. Providing a driver for a particular scanner allows it to be accessed by any program written to use this interface.The interface is implemented by a run-time library and a driver program. All drivers must provide the entry points necessary for the run-time library to provide the interface described in this document. In order to provide access to scanner-specific capabilities, scanner drivers are free to expand the interface, which is then accessed by scanner-specific programs that have standard ways of being invoked by application programs. (See IDREF="87965" TYPE="TITLE"Chapter 8, "Scanner-Specific Options.")For more details on the functions described in this chapter, see the online manual pages.LBL="" HELPID=""ID="62698"Coordinate System for ScanningID="chap92"When describing an area to be scanned, a coordinate system with the origin (0,0) in the upper left corner of the scannable area is used. The x-coordinate increases from left to right, and the y-coordinate increases from top to bottom.Note that this is the upper left corner of the document being scanned; in the case of a flatbed scanner where the document is placed face down in the bed, this is the upper right corner or lower left corner of the bed.When functions in the interface specify measurements along the horizontal and vertical axes of the scan area, the following units can be used to specify distance:COLUMNS="2"LEFT="0" WIDTH="66"SC_INCHESLEFT="75" WIDTH="172"Specify measurements in inches.LEFT="0" WIDTH="66"SC_CENTIMLEFT="75" WIDTH="172"Specify measurements in centimeters.LEFT="0" WIDTH="66"SC_PIXELSLEFT="75" WIDTH="172"Specify measurements in pixels.LBL="" HELPID=""ID="38931"Data StructuresThis section describes the generic scanner interface data structures.LBL="" HELPID=""SCANNER Data Structuretypedef struct tag_scanner {
...
} SCANNER;The application maintains a pointer to a SCANNER data structure (obtained from SCOpen()) to specify the scanner to which operations should be applied.LBL="" HELPID=""SCDATATYPE Data StructureID="chap93"Scanners support a variety of output data types. The SCDATATYPE structure encapsulates the common output data types produced by scanners.typedef struct tag_scdatatype {
unsigned int packing : 4;
unsigned int channels : 4;
unsigned int type : 8;
unsigned int bpp : 8;
} SCDATATYPE;The structure has these four fields:packingThe packing field can take on the following values:COLUMNS="2"LEFT="0" WIDTH="86"SC_PACKPIXLEFT="95" WIDTH="175"All the data for each pixel is stored
together; for example, a line of 24-bit
color is stored as RGBRGBRGB.LEFT="0" WIDTH="86"SC_PACKBANDLEFT="95" WIDTH="175"Each line of data is decomposed into
its channels; for example, a line of
24-bit color is stored as RRRGGGBBB.LEFT="0" WIDTH="86"SC_PACKPLANELEFT="95" WIDTH="175"All the data for a channel is stored
separately from other channels. A
page of color data is split into three
pages of data; one for red, one for blue,
and one for green.channelNumber of components per pixel. Legal values are 1, 3, and 4. See type below.typeType of data. This parameter indicates how the data in the various channels is to be interpreted:COLUMNS="2"LEFT="0" WIDTH="59"SC_MONOLEFT="65" WIDTH="208"Monochrome: 1 channel and 1 bit per pixel.LEFT="0" WIDTH="59"SC_GREYLEFT="65" WIDTH="208"Gray-scale: 1 channel.LEFT="0" WIDTH="59"SC_RGBLEFT="65" WIDTH="208"Red, green, and blue: 3 channels.LEFT="0" WIDTH="59"SC_CMYLEFT="65" WIDTH="208"Cyan, magenta, and yellow: 3 channels.LEFT="0" WIDTH="59"SC_CMYKLEFT="65" WIDTH="208"Cyan, magenta, yellow, and black: 4 channels.bppBits Per Pixel (per channel). The number of bits per pixel in each channel. For monochrome data, there is 1 bit per pixel. For 24-bit RGB color, there are 8 bits per pixel (x 3 channels = 24 bits).LBL="" HELPID=""ID="94828"Data Type ConventionsID="chap94"Generic scanner applications need not be written to support any particular data type. There are four basic data types that are typically used:Monochrome. ID="chap95"All scanner drivers must support this monochrome format:packing = SC_PACKPIXchannels = 1type = SC_MONObpp = 1Eight-bit gray-scale. All scanner drivers that support any type of gray-scale or color output must support the following 8-bit gray-scale format:packing = SC_PACKPIXchannels=1type = SC_GREYbpp = 8Planar 24-bit RGB color. The red, green, and blue channels are scanned in three separate passes; in this case, the data type format isID="chap96"packing = SC_PACKPLANEchannels = 3type = SC_RGBbpp = 8Packed 24-bit RGB color. This applies to a one-pass color scanner that gets all of the data in one pass. The data type for color data from this kind of scanner isID="chap97"packing = SC_PACKPIXchannels = 3type = SC_RGBbpp = 8A scanning application that is prepared to deal with these four data types should be able to interact well with any well-behaved scanner driver.LBL="" HELPID=""ID="84083"FunctionsLBL="" HELPID=""Diagnostic FunctionsMany of the functions specified here return 0 upon success and -1 in the event of a failure. If a function's return value indicates failure, the reason for the failure can be determined by examining the value of the global variable SCerrno. SCerrno will be between 0 and LASTERRNO (defined in /usr/include/sys/errno.h) if the failure was due to a failed system call, and between SCEBASE and SCELAST (defined in scanner.h) if the failure was for some other reason. #define entries for the values between SCEBASE and SCELAST can be found in /usr/include/scanner.h.IDREF="89133" TYPE="TABLE"Table 9-1 lists the diagnostic functions.COLUMNS="2"LBL="9-1"Table 9-1 ID="89133"Diagnostic FunctionsID="chap98"LEFT="0" WIDTH="68"FunctionLEFT="75" WIDTH="270"DescriptionLEFT="0" WIDTH="68"SCPerror()LEFT="75" WIDTH="270"Prints an error string.LEFT="0" WIDTH="68"SCErrorString()LEFT="75" WIDTH="270"Returns a character string containing an error message.LBL="" HELPID=""SCPerror() FunctionID="chap99"ID="chap910"void SCPerror(char *ident)This function prints the value of ident, a colon, and a string of text corresponding to the current value of SCerrno.LBL="" HELPID=""SCErrorString() FunctionID="chap911"ID="chap912"char *SCErrorString(int err)This function returns a character string containing a useful message describing the error condition represented by err. If err is not in the range 0 to LASTERRNO or SCEBASE to SCELAST, SCErrorString() returns a text string containing the words "Error code err," where err is the value passed to SCErrorString().LBL="" HELPID=""Application/Driver Rendezvous FunctionsUsers refer to scanners by names given to them at install time. The installer uses scanners(1M), which adds entries to a mapping from scanner names to (driver, device, options) tuples. The mapping is contained in the file /var/scan/scanners. The driver and device components are used to start the right driver on the device to access the scanner given by name, and options is the scanner-specific options program. scanners allows the specification of a default scanner.The application/driver Rendezvous functions are listed in IDREF="68571" TYPE="TABLE"Table 9-2 and described below.COLUMNS="2"LBL="9-2"Table 9-2 ID="68571"Application/Driver Rendezvous FunctionsID="chap913"LEFT="0" WIDTH="108"FunctionLEFT="115" WIDTH="228"DescriptionLEFT="0" WIDTH="108"SCOpen()LEFT="115" WIDTH="228"Prepares to perform operations on the scanner named by
name.LEFT="0" WIDTH="108"SCOpenScreen()LEFT="115" WIDTH="228"Calls the screen scanner driver to scan from the specified
screen.LEFT="0" WIDTH="108"SCOpenFile()LEFT="115" WIDTH="228"Calls the file scanner driver to scan from the specified
file.LEFT="0" WIDTH="108"SCClose()LEFT="115" WIDTH="228"Breaks the connection between the application and the
driver.LEFT="0" WIDTH="108"SCSetScanEnt()LEFT="115" WIDTH="228"Opens the scanner configuration file and returns a
pointer.LEFT="0" WIDTH="108"SCGetScanEnt()LEFT="115" WIDTH="228"Gets a SCANENT structure for each installed scanner.LEFT="0" WIDTH="108"SCEndScanEnt()LEFT="115" WIDTH="228"Frees the resources used to enumerate scanners.LEFT="0" WIDTH="108"SCScannerName()LEFT="115" WIDTH="228"Returns the name associated with the scanner at
installation.LEFT="0" WIDTH="108"SCScannerEnt()LEFT="115" WIDTH="228"Returns the SCANENT structure of an open scanner.LEFT="0" WIDTH="108"SCDefaultScannerName()LEFT="115" WIDTH="228"Gets the default scanner name, if any.LBL="" HELPID=""SCOpen() FunctionID="chap914"ID="chap915"SCANNER *SCOpen(char *name)The SCOpen() function prepares to perform operations on the scanner named by name by starting the appropriate driver on the appropriate device. SCOpen() performs the lookup in the name -> (driver, device, options) mapping. If name is NULL, the default scanner is used.SCOpen() returns a pointer to a SCANNER struct if successful, or NULL if there is an error. If name is NULL and no default scanner has been set, SCOpen() opens the first scanner found in /usr/lib/scan/scanners.LBL="" HELPID=""SCOpenScreen() FunctionID="chap916"ID="chap917"SCANNER *SCOpenScreen(char *screen)This function invokes the screen scanner driver to scan from the specified screen. It returns a pointer to a SCANNER struct if successful, NULL if there is an error.LBL="" HELPID=""SCOpenFile() FunctionID="chap918"ID="chap919"SCANNER *SCOpenFile(char *file)This function invokes the file scanner driver to scan from the specified file. It returns a pointer to a SCANNER struct if successful, NULL if there is an error.LBL="" HELPID=""SCClose() FunctionID="chap920"ID="chap921"int SCClose(SCANNER *s)This function breaks the connection between the application and the driver program. It returns 0 on success, -1 if there is an error.LBL="" HELPID=""SCSetScanEnt() FunctionID="chap922"ID="chap923"FILE *SCSetScanEnt(void)This function opens the scanner configuration file. It returns a pointer to the open FILE structure on success, NULL if there is an error.LBL="" HELPID=""SCGetScanEnt() FunctionID="chap924"ID="chap925"typedef struct tag_scanent {
char *name;
char *driver;
char *device;
char *options;
} SCANENT;SCANENT *SCGetScanEnt(FILE *fp)To get a SCANENT structure for each scanner installed on the system, this function should be called repeatedly until it returns NULL. The contents of the memory pointed to by the return value of SCGetScanEnt() are undefined after any subsequent calls to this function, so copy the return value if you need to preserve it across calls to SCGetScanEnt().LBL="" HELPID=""SCEndScanEnt() FunctionID="chap926"ID="chap927"int SCEndScanEnt(FILE *fp)This function frees the resources used to enumerate scanners. It returns 0 on success, -1 if there is an error.LBL="" HELPID=""SCScannerName() FunctionID="chap928"ID="chap929"char *SCScannerName(SCANNER *s)This function returns the name associated with the scanner at installation. Applications can use this to get at the name of the default scanner being used if SCOpen() was called with NULL. It returns a pointer to a character string on success, NULL if there is an error. The memory pointed to by the return value of SCScannerName() belongs to libscan and should not be modified or freed.LBL="" HELPID=""SCScannerEnt() FunctionID="chap930"ID="chap931"SCANENT *SCScannerEnt(SCANNER *s)This function returns a SCANENT structure describing an open scanner. The memory pointed to by the returned value of SCScannerEnt() belongs to libscan and should not be modified or freed.LBL="" HELPID=""SCDefaultScannerName() FunctionID="chap932"ID="chap933"char *SCDefaultScannerName(void)This function gets the default scanner name, if any. It returns the name of the default scanner, or NULL if no default scanner has been set. The memory pointed to by the returned value of SCDefaultScannerName() belongs to libscan and should not be modified or freed.LBL="" HELPID=""Scanning Resolution FunctionsID="chap934"Scanners typically support a range of resolutions (pixels per inch). Scanner drivers should support any resolution between the minimum and maximum resolutions supported by the scanner, decimating or replicating pixels as necessary to support the requested resolution. This gives the application the opportunity to preview the scanning area in an arbitrarily sized window.It is not the scanner driver's responsibility to perform higher-quality scaling of the image data. SCGetScannerRes() can be used by the scanner application to determine which resolutions are supported directly by the scanner without decimation or replication by the driver.LBL="" HELPID=""SCGetScannerRes() FunctionID="chap935"ID="chap936"int SCGetScannerRes(SCANNER *s, int metric,
float **xres, float **yres, int *nres)This function returns arrays of hardware-supported resolutions. The xres and yres arrays specify supported horizontal and vertical resolutions. metric should be one of SC_INCHES or SC_CENTIM. nres sets the number of resolution pairs in the xres and yres arrays. SCGetScannerRes() returns 0 if successful, -1 if there is an error.LBL="" HELPID=""SCGetMinMaxRes() FunctionID="chap937"ID="chap938"int SCGetMinMaxRes(SCANNER *s, int metric,
float *minx, float *miny, float *maxx, float *maxy);This function determines the resolution bounds; that is, the minimum and maximum horizontal and vertical resolutions that the scanner supports. It is an error to call SCGetMinMaxRes() with metric equal to SC_PIXELS. SCGetMinMaxRes() returns 0 if successful, -1 if there is an error.LBL="" HELPID=""Scanning Area FunctionsID="chap939"A scan may be limited by the application to a subset of the scannable area supported by the scanner. SCGetPageSize() is provided so that applications can determine the size of the scannable area supported by the scanner.LBL="" HELPID=""SCGetPageSize() FunctionID="chap940"ID="chap941"int SCGetPageSize(SCANNER *s, int metric, float *x, float *y,
float *width, float *height)This function gets the entire scannable area. It is an error to call it with metric equal to SC_PIXELS. SCGetPageSize() returns 0 if successful, -1 if there is an error.LBL="" HELPID=""SCGetDataTypes() FunctionID="chap942"ID="chap943"int SCGetDataTypes(SCANNER *s, SCDATATYPE **dt, int *ntypes)This function sets *dt to point to an array of the data types supported by the scanner driver. ntypes gets the number of data types supported. The memory pointed to by *dt belongs to libscan and should not be modified or freed. It should also not be expected to retain its values after subsequent calls to SCGetDataTypes().LBL="" HELPID=""Scanning FunctionsAfter SCOpen() has been called, the scanner is idle. In order to initiate a scan, the functions SCSetup() and SCScan() are called. Characteristics of the data to be scanned can be determined with SCGetScanSize(). A scan in progress can be aborted at any time with the function SCAbort(). The scanner status can be determined by calling the function SCGetStatus().IDREF="11706" TYPE="TABLE"Table 9-3 lists the available scanning functions.COLUMNS="2"LBL="9-3"Table 9-3 ID="11706" (continued) Scanning FunctionsID="chap944"LEFT="0" WIDTH="90"FunctionLEFT="95" WIDTH="264"DescriptionLEFT="0" WIDTH="90"SCSetup()LEFT="95" WIDTH="264"Prepares the scanner for a scan.LEFT="0" WIDTH="90"SCGetScanSize()LEFT="95" WIDTH="264"Determines the width, height, and number of bytes per scan line.LEFT="0" WIDTH="90"SCScan()LEFT="95" WIDTH="264"Starts scanning.LEFT="0" WIDTH="90"SCGetScanLine()LEFT="95" WIDTH="264"Retrieves scan line data.LEFT="0" WIDTH="90"SCDataReady()LEFT="95" WIDTH="264"Determines whether any data is available.LEFT="0" WIDTH="90"SCGetFD()LEFT="95" WIDTH="264"Returns the file descriptor for scan data.LEFT="0" WIDTH="90"SCScanFD()LEFT="95" WIDTH="264"Starts scanning (alternative call).LEFT="0" WIDTH="90"SCAbort()LEFT="95" WIDTH="264"Aborts the current scan.LEFT="0" WIDTH="90"SCGetStatus()LEFT="95" WIDTH="264"Gets the status of the scanner.LEFT="0" WIDTH="90"SCGetStatusFD()LEFT="95" WIDTH="264"Returns a file descriptor for scan status.LBL="" HELPID=""SCSetup() FunctionID="chap945"ID="chap946"SCSetup(SCANNER *s, int preview, SCDATATYPE *type,
int rmetric, float xres, float yres,
int wmetric, float x, float y, float width,
float height)This function is used to prepare the scanner for a scan. The type of data, the resolution, and the scanning area are specified. preview is nonzero if this is a "preview" scan; that is, when the driver is faced with a trade-off between speed and image quality, it should choose speed, because this is not the "real" scan. After calling SCSetup(), SCScan() is called to initiate scanning. SCSetup() returns 0 if successful, -1 if there is an error.LBL="" HELPID=""SCGetScanSize() FunctionID="chap947"ID="chap948"int SCGetScanSize(SCANNER *s, int *width, int *height,
int *bytesPerLine)This function is called after SCSetup() to determine the width, height, and number of bytes per scan line that will be returned by the driver. It returns 0 if successful, -1 if there is an error.LBL="" HELPID=""SCScan() FunctionID="chap949"ID="chap950"int SCScan(SCANNER *s)This function tells the driver to start scanning. The driver immediately starts to scan and buffer the data. SCScan() does not fetch any scan data (see SCGetScanLine()). SCScan() returns 0 if successful, -1 if there is an error.LBL="" HELPID=""SCGetScanLine() FunctionID="chap951"ID="chap952"int SCGetScanLine(SCANNER *s, void *buf, int bytes)This function retrieves scan line data. bytes should be set to the number of bytes in a scan line as determined by SCGetScanSize().Note that for color planar data, SCGetScanLine() is called once for each line in each plane of data. For 100 lines of 24-bit RGB planar data, SCGetScanLine() is called a total of 300 times, with the first 100 calls retrieving the red plane, the second 100 calls retrieving the green plane, and the third 100 calls retrieving the blue plane.LBL="" HELPID=""SCDataReady() FunctionID="chap953"ID="chap954"int SCDataReady(SCANNER *s)This function is used to determine whether any data is available for calls to SCGetScanLine(); that is, whether a call to SCGetScanLine() will block waiting for data to become available.SCDataReady() returns 1 if data is available (SCGetScanLine() will not block), 0 if no data is available (SCGetScanLine() will block), or -1 if there is an error. It is an error to call SCDataReady() if scanning was started by a call to SCScanFD().LBL="" HELPID=""SCGetFD() FunctionID="chap955"ID="chap956"int SCGetFD(SCANNER *s)This function returns the file descriptor over which scan data from the scanner driver comes. Checking the state of this descriptor with the select(2) system call is equivalent to calling SCDataReady(). If SCScanFD() was called, SCGetFD() returns the file descriptor that was passed to that function. SCGetFD() returns -1 if there is an error.LBL="" HELPID=""SCScanFD() FunctionID="chap957"ID="chap958"int SCScanFD(SCANNER *s, int fd)This function is an alternative to calling SCScan() to start scanning and SCGetLine() to fetch the data. After SCScanFD() is called, the driver writes the scanned data to fd; this is useful if the output data format of the scanner interface matches the input data type of another interface. SCScanFD() returns 0 if successful, -1 if there is an error.LBL="" HELPID=""SCAbort() FunctionID="chap959"ID="chap960"int SCAbort(SCANNER *s)This function aborts the current scan. Data buffered by the driver is discarded. SCAbort() returns 0 if successful, -1 if there is an error.LBL="" HELPID=""SCGetStatus() FunctionID="chap961"ID="chap962"enum scstate { SC_READY, SC_SCANNING, SC_ERROR };
typdef struct tag_scstatus {
enum scstate state; /* ready, scanning, error */
int errno; /* only valid if state == SC_ERROR */
long curline; /* current line being scanned */
int pass; /* current scanning pass */
} SCSTATUS;
int SCGetStatus(SCANNER *s, SCSTATUS *st)This function gets the status of the scanner. It returns 0 if successful, -1 if there is an error.LBL="" HELPID=""SCGetStatusFD() FunctionID="chap963"ID="chap964"int SCGetStatusFD(SCANNER *s)This function returns a file descriptor that can be passed to the select(2) system call. When select indicates that the file descriptor is ready for reading, the scanner driver has updated the scanning status. Retrieve the status by calling SCGetStatus(); do NOT pass the file descriptor returned from SCGetStatusFD() to any other system call.SCGetStatusFD() provides a mechanism whereby it is not necessary for an application to periodically call SCGetStatus() in a timer loop to detect changes in scanner status. SCGetStatusFD() returns -1 if there is an error.LBL="" HELPID=""Document Feeder FunctionsID="chap965"The scanner interface has provisions for the support of scanners that have document feeders attached. This facilitates the development of applications that can scan multiple pages without user intervention. IDREF="28208" TYPE="TABLE"Table 9-4 lists the document feeder functions.COLUMNS="2"LBL="9-4"Table 9-4 ID="28208"Document Feeder FunctionsLEFT="0" WIDTH="86"FunctionLEFT="95" WIDTH="252"DescriptionLEFT="0" WIDTH="86"SCFeederGetFlags()LEFT="95" WIDTH="252"Gets the feeder flags.LEFT="0" WIDTH="86"SCFeederSetFlags()LEFT="95" WIDTH="252"Sets feeder flags.LEFT="0" WIDTH="86"SCFeederAdvance()LEFT="95" WIDTH="252"Advances the feeder to the next document.LEFT="0" WIDTH="86"SCFeederReady()LEFT="95" WIDTH="252"Checks if the feeder is ready for feeding.LBL="" HELPID=""SCFeederGetFlags() FunctionID="chap966"ID="chap967"typedef unsigned int SCFEEDERFLAGS;
#define SC_HASFEEDER 1
#define SC_AUTOFEED 2
#define SC_PROGFEED 4
int SCFeederGetFlags(SCANNER *s, SCFEEDERFLAGS *flags);This function fills in the flags variable with flags appropriate for the scanner associated with s. If SC_AUTOFEED and SC_PROGFEED are both set, SCFeederSetFlags() should be called before any calls to SCScan() to establish how the application is to interact with the feeder. The meanings of the flags are as follows:COLUMNS="2"LEFT="0" WIDTH="85"SC_HASFEEDERLEFT="90" WIDTH="252"Set if there is a document feeder attached to the scanner.LEFT="0" WIDTH="85"SC_AUTOFEEDLEFT="90" WIDTH="252"Set if the feeder can operate such that each call to
SCScan() causes the next document to be loaded.LEFT="0" WIDTH="85"SC_PROGFEEDLEFT="90" WIDTH="252"Set if the feeder can operate so that SCScan() can be
called multiple times per document. It is necessary to
call SCFeederAdvance() to load the next document.SCFeederGetFlags() returns 0 if successful, -1 if there is an error.LBL="" HELPID=""SCFeederSetFlags() FunctionID="chap968"ID="chap969"int SCFeederSetFlags(SCANNER *s, SCFEEDERFLAGS flags);This function should be called before calling SCScan() for scanners in which SCFeederGetFlags() sets both SC_AUTOFEED and SC_PROGFEED. After calling SCFeederSetFlags(s, SC_AUTOFEED), the feeder advances to the next document after every call to SCScan(). After calling SCFeederSetFlags(s, SC_PROGFEED), a call to SCFeederAdvance() is necessary to advance to the next document. SCFeederSetFlags() returns 0 if successful, -1 if there is an error.LBL="" HELPID=""SCFeederAdvance() FunctionID="chap970"ID="chap971"int SCFeederAdvance(SCANNER *s)This function advances the feeder to the next document. This call is valid only if the scanner supports the SC_PROGFEED mode. For scanners that support both the SC_AUTOFEED and SC_PROGFEED modes, SCFeederSetFlags(s, SC_PROGFEED) must have been called previously.SCFeederAdvance() returns 0 if successful, -1 if there is an error. When unloading the last document, this function returns -1 with SCerrno set to SCFEEDEREMPTY.LBL="" HELPID=""SCFeederReady() FunctionID="chap972"ID="chap973"int SCFeederReady(SCANNER *s)This function checks if the feeder is ready for feeding. SCFeederReady() returns 0 if the feeder is ready, -1 if not. If the feeder is empty, SCerrno is set to SCFEEDEREMPTY; if any other error conditions exist, SCerrno is set appropriately.Note that this function needs to be called before SCFeederAdvance() to determine whether a document is ready to be scanned after the call to SCFeederAdvance().LBL="" HELPID=""EventsScanner applications need to be aware that the configuration information about a scanner obtained from SCGetMinMaxRes(), SCGetScannerRes(), SCGetPageSize(), and SCGetDataTypes() can change. This typically happens when the user selects a new input medium using the scanner specific options panel. For example, some scanners support transparency options that have a different scanning page size than the normal scanning bed. When the user decides to scan transparencies, the driver notifies the application that it needs to call SCGetPageSize() by sending an event. See IDREF="62874" TYPE="TABLE"Table 9-5.COLUMNS="2"LBL="9-5"Table 9-5 ID="62874"Event FunctionsLEFT="0" WIDTH="81"FunctionLEFT="90" WIDTH="252"DescriptionLEFT="0" WIDTH="81"SCGetEvent()LEFT="90" WIDTH="252"Receives an event from the scanner driver.LEFT="0" WIDTH="81"SCEventPending()LEFT="90" WIDTH="252"Tests whether an event is currently pending.LEFT="0" WIDTH="81"SCGetEventFD()LEFT="90" WIDTH="252"Obtains an event file descriptor for passing to select.LBL="" HELPID=""SCGetEvent() Functiontypedef struct tag_infoChange {
unsigned int pageSizeChanged : 1;
unsigned int resolutionChanged : 1;
unsigned int dataTypesChanged : 1;
unsigned int feederFlagsChanged : 1;
} SCINFOCHANGE;
#define SCEVENT_INFOCHANGE 1
typedef struct tag_scevent {
unsigned int eventType;
union {
SCINFOCHANGE infoChange;
} event;
} SCEVENT;
int SCGetEvent(SCANNER *s, SCEVENT *event)SCGetEvent() is called to receive an event from the scanner driver. The event structure should be examined, and if the pageSizeChanged field is set, the application should call SCGetPageSize() to query the new page size; if the resolutionChanged field is set, the application should call SCGetMinMaxRes() and SCGetScannerRes() to query the new resolutions; if the dataTypesChanged field is set, the application should call SCGetDataTypes() to query the new data types, and if the feederFlagsChanged field is set, the application should call SCGetFeederFlags() to query the new feeder flags.LBL="" HELPID=""SCEventPending() Functionint SCEventPending(SCANNER *s)SCEventPending() is called to test whether or not an event is currently pending. If an event is pending, the application should call SCGetEvent() to receive it. SCEventPending() returns 1 if any events are pending, and 0 if no events are pending.LBL="" HELPID=""SCGetEventFD() Functionint SCGetEventFD(SCANNER *s)SCGetEventFD() returns a file descriptor that can be passed to the select system call. When select indicates that this file descriptor is ready for reading, then an event is pending and the application should call SCGetEvent() to retrieve it.LBL="10"ID="11368"Testing for Impressario CompatibilityThis chapter explains how to use the programs that test printing compatibility with the Impressario environment.The following topics are discussed in this chapter:IDREF="18813" TYPE="TITLE""Testing Impressario Printing Compatibility"IDREF="25943" TYPE="TITLE""Testing an Impressario Printer"IDREF="61747" TYPE="TITLE""Testing an Impressario Printer Software Installation"LBL="" HELPID=""ID="18813"Testing Impressario Printing CompatibilityID="chap101"ID="chap102"The Impressario Developer's Kit provides two programs for testing printing compatibility with the Impressario environment. The testipr program tests the output capabilities of an Impressario supported printer. The testiconfig program tests an Impressario printer software installation. Both of these programs are located in the directory /usr/impressario/tests/print.The use of these test harnesses is not sufficient testing to ensure the quality of your product. They are only helpful tools, not a substitute for additional testing.LBL="" HELPID=""ID="25943"Testing an Impressario PrinterID="chap103"A printer supported by Impressario can print a wide range of file formats with a large selection of printing options for each file format. Testing each supported file format and printing option can be a laborious task if done manually, one test case at a time. testipr automates the testing process by printing a set of standard test files, according to a standard test plan.testiprID="chap104" is in the directory /usr/impressario/tests/print and typically is run from there. The name of a printer installed on the system is the only required command-line parameter. It is recommended that the printer be physically connected to the system on which testipr is run. It is the responsibility of the user to ensure that the printer is not used by other users during testing.On startup, testipr looks in the /usr/impressario/tests/print directory for test configuration files. These files are identified by a .ipr suffix and a basename corresponding to the test class name. There are three standard configuration files: text.ipr, image.ipr, and postscript.ipr. These files contain the text, image, and PostScript test classes, respectively. Each configuration file describes a set of tests to be run by testipr. These files should not be modified. If you wish to create your own test cases, copy the existing configuration files to a new location, modify them to suit your needs, and use the -p command-line option to tell testipr where to find the files.The format of the configuration file follows that of a X Window System resource file. For example:! This is a comment in an example .ipr file
test.2.desc: "SGI Image File - rotated 90, gamma 3.5"Each resource must start with the keyword test. basePath is an optional resource that specifies a directory path. If it is specified, the path will be prepended to each file resource. The file resource specifies a test file to print. Typically, these test files are from /usr/impressario/test/data. The options resource specifies the actual -o model file options to be used in the test. Note that the -o should not be specified. The testipr program automatically prepends the nobanner option to all option strings. The option string is passed as the argument to the lp command's -o option. The desc resource provides a description of the test. This string is written to the test log file. Each test case must be numbered consecutively, starting with 1.The file specified in each test is submitted for printing using the specified printing options. A log file, called /var/tmp/testipr.<printerName>.log, is created. This log file contains general information about the printer being tested and its host environment. The log also contains a detailed list of all tests performed and their corresponding spooling system print job IDs. A complete test record consists of the printer output, the corresponding log file, and the /var/spool/lp/log file. See the testipr(1) reference page for command-line options and the most up-to-date information on this test program.Example 1:Run all tests on the printer hp4.testipr hp4Example 2:Run only image tests on the printer hp4.testipr -c image hp4Example 3:Run only image tests numbers 5 and 6 on the printer hp4.testipr -c image -t 5,6 hp4LBL="" HELPID=""ID="61747"Testing an Impressario Printer Software InstallationID="chap105"An Impressario supported printer has greatly enhanced printing capabilities over other types. To provide these enhanced capabilities, software complying with Impressario specifications must be installed in standard locations. The testiconfigID="chap106" program checks that the software support for a printer conforms to Impressario specifications. Typical users of this program are third-party printer developers who wish to verify that their printer support is compatible with the Impressario printing environment.testiconfig performs a number of checks to ensure conformance to Impressario printer support specifications. The program performs checks on the printer model file, POD files, graphical options panel and printer driver. All output is sent to the standard output. If the -v option is specified, additional information is displayed during the test. The testiconfig program requires the name of the printer model file. The printer support software must be installed on the system on which the testiconfig is run. Note that a printer need not be physically installed on the system or installed by the spooling system to run this test program.For example:Test the installation for an HP LaserJet 4:testiconfig -v laserjetPJL_modelSee the testiconfig(1) reference page for command-line options and the most up-to-date information on this program.LBL="11"ID="78690"Packaging Your Impressario ProductID="chap111"This chapter explains how to package your Impressario Product.The following topics are discussed in this chapter:IDREF="90479" TYPE="TITLE""Making a tar Archive for Software Distribution"IDREF="69360" TYPE="TITLE""Packaging Impressario Printing Software"IDREF="91459" TYPE="TITLE""Packaging Impressario Scanning Software"LBL="" HELPID=""OverviewImpressario provides an open printing and scanning environment. Third-party support for printers and scanners can be added to the Impressario environment by following the procedures described in this chapter.There are two methods of packaging Impressario software for distribution: the swmgr software packaging and installation technology and tar archives. We recommend using swmgr, which users access with the Software Manager option in the System Toolchest, because of its flexibility and ease of use. Instructions for creating an image that can be installed by swmgr are in the Software Packager User's Guide. In the next section, IDREF="68163" TYPE="TABLE"Table 11-1 (for printers) and IDREF="95044" TYPE="TABLE"Table 11-2 (for scanners) define the locations, ownership, and privileges of the files that are typically needed to create an Impressario product.If you prefer to create a tar archive, the following section describes how to create one for installing Impressario drivers. LBL="" HELPID=""ID="90479"Making a tar Archive for Software DistributionID="chap112"To create a tar archive for your software distribution, use the following procedure:Become superuser. The creation of all tape archives and the subsequent installation of the product by the end user must be done as superuser. Becoming superuser is typically accomplished by either logging in as root or executing the su command. Typically, a password must be provided to gain superuser access to a system. Ask your system administrator for assistance.Copy the files that compose your product from your development area to the directories into which they will be installed. See IDREF="69360" TYPE="TITLE""Packaging Impressario Printing Software" and IDREF="91459" TYPE="TITLE""Packaging Impressario Scanning Software" for the files typically installed by printing and scanning products.Change the permissions and ownership of each file according to the recommendations in IDREF="69360" TYPE="TITLE""Packaging Impressario Printing Software" and IDREF="91459" TYPE="TITLE""Packaging Impressario Scanning Software." The chmod command is used to change file permissions and the chown command is used to change file ownership. For example, to give the file foo read¡write permission for the owner and read-only permission for all others, and to specify a root owner and sys group, enter the following commands:chmod 0644 foochown root.sys fooEnter the tar command and specify the absolute pathname of each file that is part of the distribution. For example, to create an archive consisting of two files and to place that archive on the default tape device, enter the following command:tar cvLf /dev/tape /usr/lib/print/mydriver /var/spool/lp/model/mymodelFor detailed information on the tar command, refer to the tar(1) manual page.Optionally, you may include in your distribution a shell script that removes the files that are installed by your product. This allows customers to reclaim the disk space used by your product if your product is no longer being used.LBL="" HELPID=""ID="69360"Packaging Impressario Printing SoftwareID="chap113"To illustrate better the process of packaging Impressario printing support software, let us create a fictitious product. The product provides Impressario support for the Blast family of printers. The Blast product line consists of the Blast 1, Blast 2CVX, and the Blast P+. Because each of the Blast printers provides similar functions, support for all of them is provided by a single model file.Impressario printing support products typically are named with the printer family, the word Print, and the lowest version number of Impressario that supports the product. In keeping with this convention, the product is named "BlastPrint for Impressario 2.0."A typical Impressario printer-support product consists of the following files:Model fileID="chap114"When the printer is registered with the spooling system, this file is copied and becomes the printer interface file. The spooling system executes this shell script for each print job.Printer driverID="chap115"This executable program communicates with the printer. The interface file invokes the driver to do the actual printing of a file. The driver sends data to the printer and updates the POD status file.POD filesID="chap116"The POD consists of three files, all with the same base name as the model file but with the suffixes .config, .status, and .log. These plain text files contain static and dynamic printer information.Graphical options panel programID="chap117"This GUI program provides graphical access to printer-specific options for users. The program is given the same base name as the model file with the suffix .gui.Graphical options panel resource fileID="chap118"This is an X Window system resource file for the graphical options panel program. The file is named with the class name of the graphical options panel program. This name must also match the GUI_CLASS variable in the model file.Manual pageID="chap119"A manual page that describes the printing product should be included. By convention, this manual page is named with the product name. The manual page must be formatted using nroff and must be compressed before installation. A product reference page template and a Makefile to perform the required formatting, compression, and installation are provided in the directory /usr/impressario/man.NoteIn order to create a reference page you must have the Documenter's Workbench product installed on the development system.The files listed in IDREF="68163" TYPE="TABLE"Table 11-1 comprise the BlastPrint product. The files are listed with their absolute pathnames, permissions, and ownership.COLUMNS="4"LBL="11-1"Table 11-1 ID="68163"Typical Printing Product FilesLEFT="0" WIDTH="77"DescriptionLEFT="85" WIDTH="204"PathnameLEFT="295" WIDTH="54"PermissionsLEFT="355" WIDTH="37"OwnerLEFT="0" WIDTH="77"Model fileLEFT="85" WIDTH="204"/var/spool/lp/model/blast_modelLEFT="295" WIDTH="54"0755LEFT="355" WIDTH="37"lp.lpLEFT="0" WIDTH="77"Printer driverLEFT="85" WIDTH="204"/usr/lib/print/blasterLEFT="295" WIDTH="54"0755LEFT="355" WIDTH="37"lp.lpLEFT="0" WIDTH="77"POD filesLEFT="85" WIDTH="204"/usr/lib/print/data/blast_model.config/usr/lib/print/data/blast_model.status/usr/lib/print/data/blast_model.logLEFT="295" WIDTH="54"066406640664LEFT="355" WIDTH="37"lp.lplp.lplp.lpLEFT="0" WIDTH="77"Graphical optionsprogramLEFT="85" WIDTH="204"/var/spool/lp/gui_model/ELF/blast_model.guiLEFT="295" WIDTH="54"0755LEFT="355" WIDTH="37"lp.lpLEFT="0" WIDTH="77"Graphical optionsresourcesLEFT="85" WIDTH="204"/usr/lib/X11/app-defaults/BlastLEFT="295" WIDTH="54"0644LEFT="355" WIDTH="37"root.sysLEFT="0" WIDTH="77"Reference pageLEFT="85" WIDTH="204"/usr/share/catman/u_man/cat1/blastprint.zLEFT="295" WIDTH="54"0444LEFT="355" WIDTH="37"root.sysBefore creating the actual software distribution, the above files must be copied to the directories indicated and given the specified ownership and permissions. Once this is done, the Impressario test program testiconfig(1) can be run to verify that the product conforms to Impressario product installation specifications.To run the testiconfig command on the BlastPrint product, execute the following:cd /usr/impressario/tests/print./testiconfig blast_modelOnce the product installation has been verified, a software distribution can be created. This is done using the tar command. Assuming you are making a tape distribution, you would issue the following command (note the use of the line continuation character "\" to allow the command line to extend over multiple lines):tar cvLf /dev/tape /var/spool/lp/model/blast_model \ /usr/lib/print/blaster \ /usr/lib/print/data/blast_model.config \ /usr/lib/print/data/blast_model.status \ /usr/lib/print/data/blast_model.log \ /var/spool/lp/gui_model/ELF/blast_model.gui \ /usr/lib/X11/app-defaults/Blast \ /usr/share/catman/u_man/cat1/blastprint.zThe resulting tape archive represents the BlastPrint product.It is recommended that copying the files to their installation directories, assigning ownership and permissions to the files, and archiving the files be automated in a shell script. This eliminates a lot of typing and provides a consistent distribution mechanism.Once the distribution tape has been created, it should be installed on a new system, that is, one that has never had BlastPrint. This is done as superuser using the commandtar xvf /dev/tapeOnce BlastPrint has been installed, the testiconfig program should again be run to verify that the installation is complete and correct. A printer should then be connected to the system and registered with the spooling system using the Printer Manager (printers). The Impressario test command testipr should be used with the newly installed printer to verify that it is able to print all supported Impressario file formats and options.If the printer was installed with the name myblaster, it can be tested by executing the commandscd /usr/impressario/tests/print./testipr myblasterThis completes the creation of an Impressario printer-support product.LBL="" HELPID=""ID="91459"Packaging Impressario Scanning SoftwareID="chap1110"To illustrate the process of packaging Impressario scanning software, you will create a fictitious product to provide Impressario support for the LowTech 100 scanner.Impressario scanning products are typically named with the scanner family, the word Scan, and the lowest version number of Impressario that supports this product. Name your product "LowTechScan for Impressario 2.0."A typical Impressario scanner-support product consists of the following files:Scanner driverThe executable program that obtains the data from a scanner.Graphical options programThis is the graphical scanner-specific options program launched from a scanning application. The program showcases a scanner's features. This program must have the same base name as the scanner driver in order to be recognized by scanners, the scanner installation tool.Graphical options resource fileThis is the X Window System resource file for the graphical options program and is named with the class name of the graphical options program. The class name must be the same as the graphical options program name, with the first letter capitalized. If this resource file is not named using these conventions, the options program will not have access to its resources when invoked for a network scanner.Reference pageA reference page should be created that describes the scanning product. By convention, this reference page is named with the product name. The reference page must be formatted using nroff and must be compressed before installation. A product reference page template and a Makefile to perform the required formatting, compression, and installation are provided in the directory /usr/impressario/man.NoteTo create a reference page, you must have the Documenter's Workbench product installed on the development system.The files listed in IDREF="95044" TYPE="TABLE"Table 11-2 compose the LowTechScan product. The files are listed with their absolute pathnames, permissions, and ownership.COLUMNS="4"LBL="11-2"Table 11-2 ID="95044"Typical Scanning Product FilesLEFT="0" WIDTH="77"DescriptionLEFT="85" WIDTH="183"PathnameLEFT="275" WIDTH="54"PermissionsLEFT="335" WIDTH="38"OwnerLEFT="0" WIDTH="77"Scanner driverLEFT="85" WIDTH="183"/usr/lib/scan/drv/lowtechLEFT="275" WIDTH="54"0755LEFT="335" WIDTH="38"root.sysLEFT="0" WIDTH="77"Graphical
options resourcesLEFT="85" WIDTH="183"/usr/lib/X11/app-defaults/LowtechLEFT="275" WIDTH="54"0644LEFT="335" WIDTH="38"root.sysLEFT="0" WIDTH="77"Manual pageLEFT="85" WIDTH="183"/usr/share/catman/u_man/cat1/lowtech.zLEFT="275" WIDTH="54"0444LEFT="335" WIDTH="38"root.sysBefore creating the actual software distribution, copy the above files to the directories indicated and give them the specified ownership and permissions. Then run the scanners tool to verify that the correct string for the LowTech 100 scanner appears in the "Install New Scanner" dialog. Finally, install a LowTech 100 scanner using the scanners tool, and make sure that gscan is able to run the graphical options program from the "Scanner Specific Options" command in the Parameters menu.Once the product installation has been verified, a software distribution can be created with the tar command. Assuming you are making a tape distribution, you would issue the following command (note the use of the line continuation character "\" to allow the command line to extend over multiple lines):tar cvLf /dev/tape /usr/lib/scan/drv/lowtech \ /usr/lib/scan/opt/lowtech \ /usr/lib/X11/app-defaults/Lowtech \ /usr/share/catman/u_man/cat1/lowtech.zThe resulting tape archive represents the LowTechScan product.It is recommended that copying the files to their installation directories, assigning ownership and permissions to the files, and archiving the files be automated in a shell script. This eliminates a lot of typing and provides a consistent distribution mechanism.Once the distribution tape has been created, it should be taken to a new system (in other words, one that has never had LowTechScan installed) and installed. This is done using the following command as superuser:tar xvf /dev/tapeOnce LowTechScan has been installed, the scanners and gscan programs should again be run to verify that the installation is complete and correct.This completes the creation of an Impressario scanner-support product.LBL="12"ID="94618"Enhancing Impressario With Plug-InsID="chap121"This chapter explains how you can add plug-ins to Impressario to satisfy needs that haven't been integrated into the base software. This allows you to dynamically update the Impressario feature set.The following topics are discussed in this chapter:Impressario automatic file type recognition and file conversion pipelineadding new file types to those that Impressario already recognizes and printsadding a new PostScript Raster Image Processor (RIP) to Impressario and switching between the standard Impressario RIP and your new RIPLBL="" HELPID=""ID="64322"How the Impressario File Conversion Pipeline WorksID="chap122"The key components of the Impressario file conversion pipeline area database of file type rules (FTRs)ID="chap123"the wstype runtime filetype recognition utilitythe fileconvert file conversion utilityLBL="" HELPID=""File Type RulesID="chap124"The file type rules of the FTR database are documented in the Indigo Magic Desktop Integration Guide, which is available as an online book and can be installed from your IRIX CD.The file type rules have two parts relevant to printing. The first is a TYPE rule for using the first 512 bytes of a file to recognize that the file is a particular type. The second is a CONVERT rule for converting that type to another type; the ultimate goal is to be able to convert any file type to a set of printable file types. Each CONVERT rule contains a pair of known types (a source and a destination), a Bourne shell command for converting from the source to the destination, and the computational cost of the conversion. Impressario builds on the standard IRIX database of filetypes by extending the FTR set to handle additional input file types, and by adding new destination file types.LBL="" HELPID=""Runtime File Type Recognition UtilityID="chap125"The ID="chap126"wstype utility is used to determine the file type of a file or set of files. It is similar to file(1) in basic operation, but has no hardcoded special cases and no /etc/magic file, relying on the compiled FTR database for typing information.See the wstype(1) reference page for additional information.LBL="" HELPID=""File Conversion UtilityID="chap127"The ID="chap128"fileconvert utility builds a directed acyclic graph out of all known file types, determines the input file type, and attempts to find the lowest-cost path from source to destination. The cost analysis is necessary because the file conversion is usually a multiple-step process.For example, suppose the goal is to print a GIF on a raster printer. There is no filter to directly convert a GIF to raster data, so fileconvert might generate a couple of alternate paths. One path is shown below:COLUMNS="2"LEFT="0" WIDTH="92"ConversionLEFT="100" WIDTH="109"FilterLEFT="0" WIDTH="92"GIF to TIFFLEFT="100" WIDTH="109"/usr/lib/print/il2stiffLEFT="0" WIDTH="92"TIFF to PostScriptLEFT="100" WIDTH="109"/usr/lib/print/stiff2psLEFT="0" WIDTH="92"PostScript to RasterLEFT="100" WIDTH="109"/usr/lib/print/psripA second path is shown below:COLUMNS="2"LEFT="0" WIDTH="92"ConversionLEFT="100" WIDTH="108"FilterLEFT="0" WIDTH="92"GIF to TIFFLEFT="100" WIDTH="108"/usr/lib/print/il2stiffLEFT="0" WIDTH="92"TIFF to SGILEFT="100" WIDTH="108"/usr/lib/print/tiff2sgiLEFT="0" WIDTH="92"SGI to PostScriptLEFT="100" WIDTH="108"/usr/lib/print/sgi2psLEFT="0" WIDTH="92"PostScript to RasterLEFT="100" WIDTH="108"/usr/lib/print/psripEach of the filters has an associated computational cost. ID="chap129"fileconvert determines the total cost of each path and chooses the lowest-cost route.If a conversion path exists, fileconvert prints a Bourne shell command string which, when executed, generates the destination file type on standard out. Most model files simply execute this shell command string, piping the results to the printer driver. This flexible, extensible mechanism enables Impressario to print virtually any recognizable file type on any printer that is compliant with Impressario.See the fileconvert(1) reference page for additional information.LBL="" HELPID=""ID="52113"Adding a New Filetype to ImpressarioID="chap1210"To extend Impressario to make a new type of file printable, you need only perform the following steps:Write a filter to convert your new type.Write an FTR rule that recognizes the new filetype.Add a CONVERT rule from that type to a known Impressario type.Install and test your changes.LBL="" HELPID=""Writing a New FilterID="chap1211"First, write a filter to convert your new type to either STIFF or PostScript, the two main formats for input to Impressario. The fileconvert utility requires that your filter be able to accept input either on standard in or from a specified filename. It should also be able to write output to standard out without using intermediate files, so that the conversion can succeed, even if the converting host has low disk space. See the Indigo Magic Desktop Integration Guide, Chapter 5, for more details. See the gif2stiff(1) reference page for an example.LBL="" HELPID=""Writing an FTRID="chap1212"Next, write an FTR that can recognize the new filetype given only the first 512 bytes of the file. See the Indigo Magic Desktop Integration Guide and the ftr(1) reference page for a description of the available primitives for matching a file's type and for a description of the additional parts of a good FTR.LBL="" HELPID=""Adding a CONVERT RuleID="chap1213"As part of your FTR, add a CONVERT rule from that type to a known Impressario type. We strongly recommend that you convert image types to the STIFF93aImage type and convert other non-image file formats to the PostScriptFile type. Refer to Appendix A and the libstiff(3) reference page for information on writing STIFF output. Note that once you convert to either a PostScriptFile or a STIFF93aImage, Impressario knows how to convert that filetype to a printable format on any printer.Model files that are compliant with Impressario also automatically set the proper environment variables for the options the user selected on the spooler command line, and the standard Impressario CONVERT rules automatically pick up the appropriate environment variables when converting these file types to printable types. This is how user-specified printing options are applied to the dynamically-constructed file conversion pipeline.LBL="" HELPID=""Installation and TestingThe easiest way to show how to test a new filetype is by example.LBL="" HELPID=""Setting Up an ExampleThe example makes the following assumptions:The new filetype is called BlastFile.The new FTR is in the directory /usr/tmp/blastfile.ftr.A sample BlastFile is in the directory /usr/tmp/sample.blastfile.All BlastFiles start with the word blastfile.A sample (although incomplete) TYPE rule for the example would look like this:TYPE BlastFile
MATCH string(0,9) == "blastfile";
LEGEND Blast Image File
CONVERT BlastFile STIFF93aImage
COST 50
FILTER /usr/lib/print/blast2stiff $IMPR_IMG2STIFFOPTSLBL="" HELPID=""Testing the New FiletypeTo test the new filetype, become root by entering:suSupplying a password, if necessary.Copy your FTR into /usr/lib/filetype/install:cp /usr/tmp/blastfiletype.ftr /usr/lib/filetype/installCompile the FTR database:cd /usr/lib/filetype ; makeSee the ftr(1) reference page if any errors occur.Run wstype to verify that Impressario now recognizes your file type:wstype /usr/tmp/sample.blastfileYou should see the following output:/usr/tmp/sample.blastfile BlastFileTry to convert that file type to a printable file type. The most printable file type in the Impressario database is ImpressarioPostScriptFile, so try that:fileconvert -d ImpressarioPostScriptFile \/usr/tmp/sample.blastfileYou should get back something like:PRINTFILES="/usr/tmp/sample.blastfile" ; /usr/lib/print/blast2stiff $IMPR_IMG2STIFFOPTS $PRINTFILES | /usr/lib/print/stiff2ps $IMPR_SGI2PSOPTSNoteThe above output appears on one line.If fileconvert does not return a valid shell command string, check the exit code of the filter. If you are in the C shell, enter:echo $statusIf you are in the Bourne shell, enter:echo $?If the exit code is not zero, then fileconvert was unable to convert your filetype. Verify that your destination filetype is convertible to a printable type by checking the CONVERT rules in the FTR database and making sure there is a conversion path from your destination type to the Impressario type, then try the above steps again.Once steps 1-5 work, verify that your filter produces valid output by entering vstiff /usr/tmp/sample.blastfileThis should bring up the vstiff previewer, which uses the FTR database of TYPE and CONVERT rules to convert to a screen-viewable STIFF file. Use the "PostScript Options..." menu choice on the File menu to choose different color spaces and depths. See the vstiff(1) reference page for more help.NoteIf your filter converts directly to STIFF93aImage, the PostScript options in vstiff are not applicable.Finally, try printing that file to an Impressario printer. Enter:lp -dprintername /usr/tmp/sample.blastfileWatch the spooler log file for errors and the printstatus panel for printer messages until the file prints. If you were able to vstiff the file, then you should to be able to print it.When you have completed this process, you should have the files shown in IDREF="34268" TYPE="TABLE"Table 12-1. These files should be installed with the permissions and the ownerships shown and at the locations shown. The actual file basename may change but the pathname should not. Conversion filters should be installed in /usr/lib/print.COLUMNS="4"LBL="12-1"Table 12-1 ID="34268"New Filetype PathnamesLEFT="0" WIDTH="54"ModeLEFT="60" WIDTH="36"OwnerLEFT="105" WIDTH="36"GroupLEFT="150" WIDTH="207"Full PathnameLEFT="0" WIDTH="54"-r--r--r--LEFT="60" WIDTH="36"rootLEFT="105" WIDTH="36"sysLEFT="150" WIDTH="207"/usr/lib/filetype/install/blastfiletype.ftrLEFT="0" WIDTH="54"-rwxr-xr-xLEFT="60" WIDTH="36"rootLEFT="105" WIDTH="36"sysLEFT="150" WIDTH="207"/usr/lib/print/blast2stiffLBL="" HELPID=""ID="49856"Using an Alternate PostScript RIPID="chap1214"Using an alternate PostScript Raster Image Processor (RIP) is extremely easy in the Impressario open architecture. You can even switch RIPs at the last possible moment without losing any of the features of the Impressario file conversion pipeline.The steps required to add an alternate RIP to your system are as follows:Make the new RIP command line compatible with the Impressario RIP, psrip.Write a dummy TYPE.Test the alternative RIP.Package the files.You should be able to use this alternate RIP instead of, or in addition to, the standard Impressario interpreter.NoteIn the example below, the new RIP is called blastrip and is installed in the directory /usr/lib/print.LBL="" HELPID=""Making the Command Line Compatible With psripYour new RIP must be command-line compatible with psrip. Look at the psrip(1) reference page for more information on what that means. psrip accepts ASCII and binary PostScript either on standard in or in a disk file, and generates a variety of sizes, colorspaces, and depths of STIFF bitmaps on standard out.Being command-line compatible with psrip is probably the most tedious part of adding a new interpreter, but is well worth the effort when you consider that you gain all the advantages of Impressario:plug-and-play printer driversautomatic file type recognitionautomatic file type conversionLBL="" HELPID=""Writing a Dummy TYPEThe next step is to write a dummy TYPE and a simple CONVERT rule. First create a new, empty TYPE definition for your output raster format. For example:TYPE BlastRasterBitmap
# convert from formatted, filtered ImpressarioPostScriptFile
# to a RIPped bitmap
COST 50
FILTER /usr/lib/print/blastrip $IMPR_PSRIPOPTSInstall that file in /usr/lib/filetype/install/blastrip.ftr and compile your FTR database by enteringsu ; cd /usr/lib/filetype ; makeNow test the conversion and preview the bitmap by using vstiff:fileconvert -d BlastRasterBitmap /etc/passwd | vstiff -stdinIf you run into problems viewing it, then save it to disk and use other tools to verify that you have a valid STIFF file. However, if vstiff cannot view it, then Impressario printer drivers will probably not be able to print it.LBL="" HELPID=""Testing the Alternate RIPTo use the alternative RIP in your printer model files instead of the default psrip, change all references to "ImpressarioRasterBitmap" to "BlastRasterBitmap." The lines below were taken from the laserjetPJL_model template model file and the word ImpressarioRasterBitmap was changed to BlastRasterBitmap:# Use fileconvert to convert to the printer's native format.
# For raster printers, it is BlastRasterBitmap.
# For PostScript printers, it is ImpressarioPostScriptFile.
#
CMD=`$fileconvert $fileconvertopts -d BlastRasterBitmap $file 2> /dev/null`LBL="" HELPID=""Packaging the FilesYou are finished now, and need only package these optional RIP files for installation. The files you should be installing may have different names, but should be installed in the following directories, with the permissions and ownerships shown in IDREF="97879" TYPE="TABLE"Table 12-2.COLUMNS="4"LBL="12-2"Table 12-2 ID="97879"Alternative RIP PathnamesLEFT="0" WIDTH="54"ModeLEFT="60" WIDTH="36"OwnerLEFT="105" WIDTH="36"GroupLEFT="150" WIDTH="207"Full PathnameLEFT="0" WIDTH="54"-r--r--r--LEFT="60" WIDTH="36"rootLEFT="105" WIDTH="36"sysLEFT="150" WIDTH="207"/usr/lib/filetype/install/blastrip.ftrLEFT="0" WIDTH="54"-rwxr-xr-xLEFT="60" WIDTH="36"rootLEFT="105" WIDTH="36"sysLEFT="150" WIDTH="207"/usr/lib/print/blastripYou should modify your printer's model file to use the new RIP whenever you want. You can, of course, still ask for ImpressarioRasterBitmap.NoteTest carefully to make sure that your new RIP is, in fact, compatible with the existing psrip before shipping your product.LBL="A"ID="68392"Stream TIFF Data FormatID="apenA1"ID="apenA2"This appendix describes the Stream TIFF data format (STIFF), the primary interchange file format between printer filters and drivers, and ID="apenA3"ID="apenA4"libstiff;, a C application program interface (API) used to read and write Stream TIFF files. Stream TIFF is also used by gscanID="apenA5" to store images in TIFF files and to scan to the screen (in conjunction with vstiff).The following major topics are discussed:IDREF="61309" TYPE="TITLE""Library Description"IDREF="13547" TYPE="TITLE""Library Access"IDREF="36728" TYPE="TITLE""Library Functions"IDREF="67200" TYPE="TITLE""Printing-Specific STIFF"IDREF="76505" TYPE="TITLE""Generic STIFF File Structure"LBL="" HELPID=""ID="61309"Library DescriptionID="apenA6"libstiff provides a C application program interface (API) to the reading and writing of Stream TIFF files. Stream TIFF (STIFF) is a subset of the Tag Image File Format (TIFF) Revision 6.0 originally developed by Aldus Corporation. TIFF is an extremely flexible format, well suited for monochrome and color bitmap images. The primary difference between TIFF and STIFF is that while a TIFF file may require file seeking during reading or writing, a STIFF file does not. This means that a STIFF file can be read and written to both files and non-seekable streams such as pipes and sockets. STIFF can be used by application developers to write TIFF 6.0-compliant files, and a STIFF file can be read by any TIFF reader that conforms to the TIFF Revision 6.0 specifications. However, libstiff cannot be used to read many standard TIFF files since STIFF is a subset of TIFF.The functions provided by libstiff greatly simplify the reading and writing of TIFF-compatible files. Using the STIFF API, TIFF 6.0-compatible STIFF files can be read and written without the need to understand the structure of a TIFF file and without the need to explicitly specify TIFF tags.LBL="" HELPID=""ID="13547"Library AccessID="apenA7"There are two sets of libstiff functions. One set comprises the generic libstiff API. These functions are designated by an ST prefix and may be used to read and write generic STIFF files. To access these functions, an application must include the header file stiff.h located in the /usr/include directory. The second set of libstiff functions is tailored to reading and writing STIFF files that are to be passed between printing filters and drivers. These printing-related functions are designated by the prefix PST and are accessed through the header file printstiff.h, also located in /usr/include. If printstiff.h is used, the header stiff.h need not be specified. The generic and printing-specific functions may be freely intermixed within an application.Programs that call libstiff functions must link with the libstiff.a library located in the directory /usr/lib. An example command line is shown below:cc -o myprog myprog.c -lstiff LBL="" HELPID=""ID="36728"Library FunctionsID="apenA8"libstiff provides the generic functions listed in IDREF="33260" TYPE="TABLE"Table A-1.COLUMNS="3"LBL="A-1"Table A-1 ID="33260" (continued) STIFF Generic FunctionsID="apenA9"LEFT="0" WIDTH="93"TaskLEFT="100" WIDTH="99"Function NameLEFT="205" WIDTH="193"DescriptionLEFT="0" WIDTH="93"Stream HandlingLEFT="100" WIDTH="99"STOpen()STClose()STSkipTo()LEFT="205" WIDTH="193"Opens a STIFF stream on the specified file
descriptorCloses a STIFF stream opened by STOpen()Skips forward on a specified streamLEFT="0" WIDTH="93"Reading and WritingLEFT="100" WIDTH="99"STReadImageHeader()STWriteImageHeader()STRead()STWrite()LEFT="205" WIDTH="193"Reads the STIFF image header from the
specified streamWrites the image header to the specified streamReads the specified amount of image data fromthe streamWrites the specified amount of image data to the
streamLEFT="0" WIDTH="93"TIFF Tag SupportLEFT="100" WIDTH="99"STAddTag()STRemoveTag()STGetTag()STPrintTags()LEFT="205" WIDTH="193"Adds the specified tag to the TIFF tag listRemoves the specified tag from the output TIFF
tag listSearches the tag list for the specified TIFF tagPrints the current TIFF tag listLEFT="0" WIDTH="93"Execution Error
HandlingLEFT="100" WIDTH="99"STPerror()STErrorString()LEFT="205" WIDTH="193"Prints error messages to standard errorGets the error string for the specified error codeSTIFF also provides the printing-specific functions listed in IDREF="76070" TYPE="TABLE"Table A-2.COLUMNS="2"LBL="A-2"Table A-2 ID="76070"STIFF Printing-Specific FunctionsID="apenA10"LEFT="0" WIDTH="103"Function NameLEFT="110" WIDTH="259"DescriptionLEFT="0" WIDTH="103"PSTReadImageHeader()LEFT="110" WIDTH="259"Reads the printing-specific STIFF image header from the streamLEFT="0" WIDTH="103"PSTWriteImageHeader()LEFT="110" WIDTH="259"Writes the printing-specific STIFF image header to the streamLBL="" HELPID=""Example UsageThe sequence of operations for writing a STIFF stream is as follows:Obtain a writable file descriptor. Note that this descriptor can be associated with a non-seekable stream.Call STOpen() with the writable file descriptor and the flag ST_WRITE.Fill in the STIFF image header (STImageHeader() or PSTImageHeader()).Optionally, add any application-specific TIFF tags to the file using STAddTag().Call the image header write function STWriteImageHeader() or PSTWriteImageHeader().Write the image data using STWrite().Repeat steps 3 through 6 for each page of image data.Close the STIFF file using STClose().Close the file descriptor.The sequence of operations for reading a STIFF stream is as follows:Obtain a readable file descriptor. Note that this descriptor can be associated with a non-seekable stream.Call STOpen() with the readable file descriptor and the flag ST_READ.Call the image header read function STReadImageHeader() or PSTReadImageHeader().Access the fields of the image header structure to determine the amount of image data to be read for this page.Optionally, retrieve any application-specific TIFF tags from the file using STGetTag().Read the image data using STRead().Repeat steps 3 through 6 for each page of image data. The last page of image data is an empty page (that is, the amount of data equals zero). An STEEOF error occurs if an attempt is made to read past the end of the STIFF.Close the STIFF stream using STClose().Close the file descriptor.If an error condition is returned by a libstiff function, STPerror() can be used to print a diagnostic error message to the standard error, and STErrorString() can be used to obtain an appropriate error message for display to the user by other means.LBL="" HELPID=""ID="67200"Printing-Specific STIFFID="apenA11"ID="apenA12"The printing-specific functions (PST) provided by libstiff read and write STIFF files as described above. The printing-specific aspect of these functions is found in the image header structure. PSTImageHeader(), the printing-specific image header, contains all fields of the STImageHeader() plus printing-specific information fields such as image resolution and halftoning method.If a STIFF file is written using the generic functions and is read using the printing-specific functions, default values are used for the PSTImageHeader() fields not found in the STIFF. Similarly, a STIFF file written using the printing-specific functions can be read by the generic functions. In this case, the additional information in the stream can be ignored or obtained using the STGetTag() function.Refer to the header file /usr/include/printstiff.h for additional information regarding printing-specific STIFF.Printer driver developers should pay special attention to the command-line options string that is part of a PST image header. See the LaserJet example driver for an example of how to combine parsing the command-line and image-header driver options.LBL="" HELPID=""ID="76505"Generic STIFF File StructureWhile it is not necessary to understand the STIFF file structure to use libstiff, this explanation is provided for those who need to know. A Stream TIFF file is first and foremost a valid TIFF file. STIFF is derived from the TIFF 6.0 specifications available from Aldus Corporation (see below). The terms used below to describe a STIFF file (for example, IFD) are explained in the TIFF specifications and are not described here.The primary restriction STIFF places on the TIFF structure is that all data must be read from or written to the file without the need to seek within the file. Specifically, within a STIFF file, these things must be true:The bitmap image data must be in page-number order.Data that does not fit in the value section of a tag must be located immediately after the IFD and must occur in the same order in which the tags are encountered. The exception to this is the image data itself, which must come last for each page.Image data must immediately follow the IFD and any associated offset values.A terminating, empty IFD is always added to the end of the STIFF file. This IFD guarantees that an IFD with 0000 in its "next IFD" field appears in the IFD chain. Note that this empty IFD is not encountered when following IFD pointers if the last "real" IFD is written with the last parameter set to 1. While the TIFF specification states that IFDs should not be empty, relaxing this restriction appears to have no impact on TIFF compatibility.A generic STIFF file can be represented as shown in IDREF="61624" TYPE="GRAPHIC"Figure A-1.FILE="apenA-2.gif" POSITION="INLINE" SCALE="FALSE"LBL="A-1"Figure A-1 ID="61624"Generic STIFF File StructureThe libstiff functions support only the Motorola« (MM) byte ordering. In addition to supporting TIFF class RGB data, libstiff supports the CMYK color image data type (PhotoMetricInterpretation = 5 and InkSet = 1) and four additional color image separation types: CMY, YMC, YMCK, and KCMY.For these additional types, PhotoMetricInterpretation = 5, InkSet = 2, NumberOfInks = 3 or 4, and the InkNames tag is used to indicate the inks contained in each channel.When reading an image header, libstiff parses the ink names for these additional types and sets the type field of the STImageHeader structure to the appropriate value defined in stiff.h. When writing an image header, libstiff writes the appropriate PhotoMetricInterpretation, InkSet, NumberOfInks, and InkNames tags based on the value of the type field of the STImageHeader structure.The CMYK data format is a TIFF data format extension, as shown in IDREF="91021" TYPE="TABLE"Table A-3.COLUMNS="2"LBL="A-3"Table A-3 ID="91021"CMYK Data FormatID="apenA13"LEFT="0" WIDTH="141"TagLEFT="150" WIDTH="191"Possible ValuesLEFT="0" WIDTH="141"BitsPerSampleLEFT="150" WIDTH="191"(1,1,1,1) (4,4,4,4) (8,8,8,8)LEFT="0" WIDTH="141"PhotoMetricInterpretationLEFT="150" WIDTH="191"5LEFT="0" WIDTH="141"SamplesPerPixelLEFT="150" WIDTH="191"4LEFT="0" WIDTH="141"PlanarConfigurationLEFT="150" WIDTH="191"1, 2LEFT="0" WIDTH="141"NumberOfInksLEFT="150" WIDTH="191"4The CMY data class is a subset of the CMYK class and differs from the CMYK class in a TIFF-compliant manner, as shown in IDREF="60632" TYPE="TABLE"Table A-4.COLUMNS="2"LBL="A-4"Table A-4 ID="60632"CMY Data FormatID="apenA14"LEFT="0" WIDTH="141"TagLEFT="150" WIDTH="191"Possible ValuesLEFT="0" WIDTH="141"BitsPerSampleLEFT="150" WIDTH="191"(1,1,1,1) (1,1,1) (4,4,4) (8,8,8)LEFT="0" WIDTH="141"PhotoMetricInterpretationLEFT="150" WIDTH="191"5LEFT="0" WIDTH="141"SamplesPerPixelLEFT="150" WIDTH="191"3 (4 or 8 bits, 1-bit planar) or 4 (1-bit chunky)LEFT="0" WIDTH="141"PlanarConfigurationLEFT="150" WIDTH="191"1, 2LEFT="0" WIDTH="141"NumberOfInksLEFT="150" WIDTH="191"3The YMC data class is similar to the CMY class except that data is organized as YMC instead of CMY (see IDREF="80190" TYPE="TABLE"Table A-5). When using libstiff, YMC data corresponds to the data type ST_TYPE_YMC.COLUMNS="2"LBL="A-5"Table A-5 ID="80190"YMC Data FormatID="apenA15"LEFT="0" WIDTH="141"TagLEFT="150" WIDTH="191"Possible ValuesLEFT="0" WIDTH="141"BitsPerSampleLEFT="150" WIDTH="191"(1,1,1,1) (1,1,1) (4,4,4) (8,8,8)LEFT="0" WIDTH="141"PhotoMetricInterpretationLEFT="150" WIDTH="191"5LEFT="0" WIDTH="141"SamplesPerPixelLEFT="150" WIDTH="191"3 (4 or 8 bits, 1-bit planar) or 4 (1-bit chunky)LEFT="0" WIDTH="141"PlanarConfigurationLEFT="150" WIDTH="191"1, 2LEFT="0" WIDTH="141"NumberOfInksLEFT="150" WIDTH="191"3LEFT="0" WIDTH="141"InkSetLEFT="150" WIDTH="191"2LEFT="0" WIDTH="141"InkNamesLEFT="150" WIDTH="191"yellow, magenta, cyanThe YMCK class is similar to the CMYK class except that data is organized as YMCK instead of CMYK (see IDREF="68069" TYPE="TABLE"Table A-6). When using libstiff, YMCK data corresponds to the data type ST_TYPE_YMCK.COLUMNS="2"LBL="A-6"Table A-6 ID="68069"YMCK Data FormatID="apenA16"LEFT="0" WIDTH="141"TagLEFT="150" WIDTH="191"Possible ValuesLEFT="0" WIDTH="141"BitsPerSampleLEFT="150" WIDTH="191"(1,1,1,1) (4,4,4,4) (8,8,8,8)LEFT="0" WIDTH="141"PhotoMetricInterpretationLEFT="150" WIDTH="191"5LEFT="0" WIDTH="141"SamplesPerPixelLEFT="150" WIDTH="191"4LEFT="0" WIDTH="141"PlanarConfigurationLEFT="150" WIDTH="191"1, 2LEFT="0" WIDTH="141"NumberOfInksLEFT="150" WIDTH="191"4LEFT="0" WIDTH="141"InkSetLEFT="150" WIDTH="191"2LEFT="0" WIDTH="141"InkNamesLEFT="150" WIDTH="191"yellow, magenta, cyan, blackThe KCMY class is similar to the CMYK class except that the data is organized as KCMY instead of CMYK (see IDREF="93476" TYPE="TABLE"Table A-7). When using libstiff, KCMY data corresponds to the data type ST_TYPE_KCMY.COLUMNS="2"LBL="A-7"Table A-7 ID="93476"KCMY Data FormatID="apenA17"LEFT="0" WIDTH="141"TagLEFT="150" WIDTH="191"Possible ValuesLEFT="0" WIDTH="141"BitsPerSampleLEFT="150" WIDTH="191"(1,1,1,1) (4,4,4,4) (8,8,8,8)LEFT="0" WIDTH="141"PhotoMetricInterpretationLEFT="150" WIDTH="191"5LEFT="0" WIDTH="141"SamplesPerPixelLEFT="150" WIDTH="191"4LEFT="0" WIDTH="141"PlanarConfigurationLEFT="150" WIDTH="191"1, 2LEFT="0" WIDTH="141"NumberOfInksLEFT="150" WIDTH="191"4LEFT="0" WIDTH="141"InkSetLEFT="150" WIDTH="191"2LEFT="0" WIDTH="141"InkNamesLEFT="150" WIDTH="191"black, cyan, magenta, yellowNote that for the RGB, CMY, and YMC classes with BitsPerSample values of (1,1,1) and a PlanarConfiguration value of 1, pixels are stored two to a byte, with the bits ordered from most-significant to least-significant.For example, CMY data is stored as CMY0CMY0Rows are padded to contain an integral number of bytes.Refer to the header file stiff.h for additional information regarding the STIFF file structure.LBL="B"ID="79172"Silicon Graphics Image File Format APIID="apenB1"This appendix describes libimp, the C application program interface (API) for reading and writing Silicon Graphics image format files.The following major topics are discussed:IDREF="45953" TYPE="TITLE""Library Description"IDREF="90079" TYPE="TITLE""Library Access"IDREF="66114" TYPE="TITLE""Library Functions"IDREF="59573" TYPE="TITLE""IMPImage Structure"LBL="" HELPID=""ID="45953"Library DescriptionID="apenB2"libimpID="apenB3" provides a C application program interface (API) for reading and writing Silicon Graphics image format files and for performing a number of format-independent image processing operations. These operations include color space conversion and filtered image zooming.libimp provides all functionality of the libimage library. (See the rgb(4) reference page for a description of libimage.) In addition, libimp provides function prototypes, a documented interface, reliable error reporting, and a number of other enhancements.LBL="" HELPID=""ID="90079"Library AccessA program that calls libimp functions must include the header file imp.h located in the directory /usr/include. In addition, the program must link with the libimp.a library located in /usr/lib. The link line would look like this:... -limp ...LBL="" HELPID=""ID="66114"Library FunctionsThe ID="apenB4"libimp library, which is based heavily on the libimage and libgutil libraries, consists of two main sets of functions. The functions shown in IDREF="75505" TYPE="TABLE"Table B-1 perform operations on Silicon Graphics image format files.COLUMNS="3"LBL="B-1"Table B-1 ID="75505"Silicon Graphics Image Format File FunctionsLEFT="0" WIDTH="61"TaskLEFT="70" WIDTH="73"FunctionLEFT="150" WIDTH="234"DescriptionLEFT="0" WIDTH="61"Image AccessLEFT="70" WIDTH="73"impOpen()LEFT="150" WIDTH="234"Opens a Silicon Graphics image format file for reading or
writingLEFT="0" WIDTH="61"LEFT="70" WIDTH="73"impOpenFd()LEFT="150" WIDTH="234"Opens a Silicon Graphics image format file for reading or
writingLEFT="0" WIDTH="61"LEFT="70" WIDTH="73"impClose()LEFT="150" WIDTH="234"Closes a Silicon Graphics image format fileLEFT="0" WIDTH="61"LEFT="70" WIDTH="73"impCloseFd()LEFT="150" WIDTH="234"Closes a Silicon Graphics image format fileLEFT="0" WIDTH="61"Image I/OLEFT="70" WIDTH="73"impReadRow()LEFT="150" WIDTH="234"Reads image rowLEFT="0" WIDTH="61"LEFT="70" WIDTH="73"impReadRowB()LEFT="150" WIDTH="234"Reads byte image rowLEFT="0" WIDTH="61"LEFT="70" WIDTH="73"impWriteRow()LEFT="150" WIDTH="234"Writes image rowLEFT="0" WIDTH="61"LEFT="70" WIDTH="73"impWriteRowB()LEFT="150" WIDTH="234"Writes byte image rowThe functions shown in IDREF="71852" TYPE="TABLE"Table B-2 perform operations on image data in a format-independent manner.COLUMNS="3"LBL="B-2"Table B-2 (continued) ID="71852"Format-Independent File FunctionsLEFT="0" WIDTH="104"TaskLEFT="110" WIDTH="97"FunctionLEFT="215" WIDTH="180"DescriptionLEFT="0" WIDTH="104"ZoomingLEFT="110" WIDTH="97"impCreateZoom()LEFT="215" WIDTH="180"Creates zoom operatorLEFT="0" WIDTH="104"LEFT="110" WIDTH="97"impDestroyZoom()LEFT="215" WIDTH="180"Destroys zoom operatorLEFT="0" WIDTH="104"LEFT="110" WIDTH="97"impResetZoom()LEFT="215" WIDTH="180"Resets zoom row cacheLEFT="0" WIDTH="104"LEFT="110" WIDTH="97"impZoomRow()LEFT="215" WIDTH="180"Zooms an image rowLEFT="0" WIDTH="104"Data PackingLEFT="110" WIDTH="97"impPackRow()LEFT="215" WIDTH="180"Packs two-byte data into one byteLEFT="0" WIDTH="104"LEFT="110" WIDTH="97"impUnpackRow()LEFT="215" WIDTH="180"Unpacks one-byte data into two bytesLEFT="0" WIDTH="104"Math OperationsLEFT="110" WIDTH="97"impZeroRow()LEFT="215" WIDTH="180"Sets row to zeroLEFT="0" WIDTH="104"LEFT="110" WIDTH="97"impInitRow()LEFT="215" WIDTH="180"Initializes a row to a valueLEFT="0" WIDTH="104"LEFT="110" WIDTH="97"impCopyRow()LEFT="215" WIDTH="180"Copies a rowLEFT="0" WIDTH="104"LEFT="110" WIDTH="97"impSAddRow()LEFT="215" WIDTH="180"Adds a value to a rowLEFT="0" WIDTH="104"LEFT="110" WIDTH="97"impVAddRow()LEFT="215" WIDTH="180"Adds two rowsLEFT="0" WIDTH="104"LEFT="110" WIDTH="97"impSSubRow()LEFT="215" WIDTH="180"Subtracts a value from a rowLEFT="0" WIDTH="104"LEFT="110" WIDTH="97"impVSubRow()LEFT="215" WIDTH="180"Subtracts two rowsLEFT="0" WIDTH="104"LEFT="110" WIDTH="97"impSMulRow()LEFT="215" WIDTH="180"Multiplies a row by a valueLEFT="0" WIDTH="104"LEFT="110" WIDTH="97"impSDivRow()LEFT="215" WIDTH="180"Divides a row by a valueLEFT="0" WIDTH="104"LEFT="110" WIDTH="97"impClampRow()LEFT="215" WIDTH="180"Clamps row valuesLEFT="0" WIDTH="104"Color Space ConversionLEFT="110" WIDTH="97"impRGBtoW()LEFT="215" WIDTH="180"Converts an array from RGB to W formatLEFT="0" WIDTH="104"LEFT="110" WIDTH="97"impWtoRGB()LEFT="215" WIDTH="180"Converts an array from W to RGB formatLEFT="0" WIDTH="104"LEFT="110" WIDTH="97"impRGBtoK()LEFT="215" WIDTH="180"Converts an array from RGB to K formatLEFT="0" WIDTH="104"LEFT="110" WIDTH="97"impKtoRGB()LEFT="215" WIDTH="180"Converts an array from K to RGB formatLEFT="0" WIDTH="104"LEFT="110" WIDTH="97"impRGBtoCMY()LEFT="215" WIDTH="180"Converts an array from RGB to CMY formatLEFT="0" WIDTH="104"LEFT="110" WIDTH="97"impCMYtoRGB()LEFT="215" WIDTH="180"Converts an array from CMY to RGB formatLEFT="0" WIDTH="104"LEFT="110" WIDTH="97"impRGBtoYIQ()LEFT="215" WIDTH="180"Converts an array from RGB to YIQ formatLEFT="0" WIDTH="104"LEFT="110" WIDTH="97"impYIQtoRGB()LEFT="215" WIDTH="180"Converts an array fromYIQ to RGB formatLEFT="0" WIDTH="104"LEFT="110" WIDTH="97"impRGBtoYUV()LEFT="215" WIDTH="180"Converts an array from RGB to YUV formatLEFT="0" WIDTH="104"LEFT="110" WIDTH="97"impYUVtoRGB()LEFT="215" WIDTH="180"Converts an array from YUV to RGB formatLEFT="0" WIDTH="104"LEFT="110" WIDTH="97"impRGBtoYCbCr()LEFT="215" WIDTH="180"Converts array from RGB to YCbCr formatLEFT="0" WIDTH="104"LEFT="110" WIDTH="97"impYCbCrtoRGB()LEFT="215" WIDTH="180"Converts array from YCbCr to RGB formatLEFT="0" WIDTH="104"LEFT="110" WIDTH="97"impRGBtoCMYK()LEFT="215" WIDTH="180"Converts array from RGB to CMYK formatLEFT="0" WIDTH="104"LEFT="110" WIDTH="97"impCMYKtoRGB()LEFT="215" WIDTH="180"Converts array from CMYK to RGB formatLEFT="0" WIDTH="104"LEFT="110" WIDTH="97"impRGBtoDevCMYK()LEFT="215" WIDTH="180"Converts array from RGB to device CMYK
formatLEFT="0" WIDTH="104"LEFT="110" WIDTH="97"impRGBtoHSV()LEFT="215" WIDTH="180"Converts an array from RGB to HSV formatLEFT="0" WIDTH="104"LEFT="110" WIDTH="97"impHSVtoRGB()LEFT="215" WIDTH="180"Converts an array from HSV to RGB formatLEFT="0" WIDTH="104"LEFT="110" WIDTH="97"impRGBtoHLS()LEFT="215" WIDTH="180"Converts an array from RGB to HLS formatLEFT="0" WIDTH="104"LEFT="110" WIDTH="97"impHLStoRGB()LEFT="215" WIDTH="180"Converts an array from HLS to RGB formatLEFT="0" WIDTH="104"Error HandlingLEFT="110" WIDTH="97"impPerror()LEFT="215" WIDTH="180"Prints libimp execution error messages to
standard errorLEFT="0" WIDTH="104"LEFT="110" WIDTH="97"impErrorString()LEFT="215" WIDTH="180"Obtains libimp execution error messagesLBL="" HELPID=""ID="59573"IMPImage StructureID="apenB5"The IMPImage structure contains public and private information about a Silicon Graphics image file. This structure is identical both in size and field naming to the IMAGE structure defined in the header file image.h, included by applications that use the libimage library. While it has been common practice to directly modify the public fields of the image structure, this is not recommended. Macros are defined in imp.h for manipulating the structure fields. It is strongly recommended that these macros be used to set and get values from the image structure. The IMPImage structure is defined as follows:typedef struct _impImage {
/******* Public image header information (archived) */
ushort_t imagic; /* Silicon Graphics image file magic number */
ushort_t type; /* Raster type (e.g. verbatim, rle) */
ushort_t dim; /* Image dimension */
ushort_t xsize; /* X size (pixels) */
ushort_t ysize; /* Y size (pixels) */
ushort_t zsize; /* Number of channels (e.g. rgb = 3) */
long min; /* Minimum intensity in image */
long max; /* Maximum intensity in image */
ulong_t wastebytes; /* Padding */
char name[IMP_NAME_MAX+1]; /* Image name */
ulong_t colormap; /* Image type (e.g. colormap, normal) */
/******* Private image header information (core use only) */
long file;
ushort_t flags;
short dorev;
short x;
short y;
short z;
short cnt;
short *ptr;
short *base;
short *tmpbuf;
ulong_t offset;
ulong_t rleend;
ulong_t *rowstart;
long *rowsize;
} IMPImage;Noteushort_t and ulong_t are unsigned short and unsigned long, respectively.Fields:magicMagic number identifying file as a Silicon Graphics image format file.typeBitwise-OR combined code indicating the raster encoding method and the number of bytes per pixel per channel. Currently, Silicon Graphics image files support either a verbatim, uncompressed raster encoding or a run-length, compressed encoding. Both of these encodings are available at one or two bytes per pixel per channel. The header file imp.h defines codes for all supported combinations of encoding methods and pixel widths.dimNumber of dimensions to the image. A colormap file has dimension one (length), a black and white image has dimension two (height and width), and an RGB image has dimension three (height, width, and depth).xsize, ysizeImage size in pixels.zsizeNumber of color channels or depth. A black and white image has one channel and an RGB image has three channels.min, maxThe minimum and maximum intensity values in the image. These values are the minimum and maximum for all channels combined.nameA descriptive name string for the image.colormapThe image type. Refer to imp.h for the supported image type codes. The field is named colormap for compatibility with the IMAGE structure used by the libimage library.LBL="" HELPID=""Image Access FunctionsID="apenB6"LBL="" HELPID=""impOpen() FunctionID="apenB7"This function opens the image file specified by fname. If mode is r, the file is opened for reading. If mode is w, the file is opened for writing and created if it does not exist, or truncated to zero length if it does exist.impOpenFd() opens the image file pointed to by the file descriptor fd. The descriptor's permissions must permit the operations specified by mode. That is, if mode is w, the descriptor must have write permission. In addition, it must be possible to seek on the specified descriptor. At this time, read/write mode is not supported for Silicon Graphics image files. Upon successful execution, both functions return a pointer to a Silicon Graphics image file structure.Synopsis:#include <imp.h>
IMPImage* impOpenFd(int fd, const char *mode, ...);In write mode, impOpen() and impOpenFd() require that these additional parameters be specified:uint_t rasterType,dimension, xSize, ySize, numChannels, imageType;
char *name;Noteuint_t stands for unsigned int.Arguments:rasterTypeSpecifies the raster encoding method and the number of bytes per pixel per channel. Silicon Graphics image format files can be written either uncompressed or with run-length encoding compression, and with one or two bytes per pixel per channel. Refer to imp.h for the supported raster types.dimensionSpecifies the number of dimensions in the image. A colormap file has dimension one, a black and white image has dimension two, and an RGB image has dimension three.xSize, ySizeSpecifies the image size in pixels.numChannelsSpecifies the number of image color channels. A black and white image has one channel and an RGB image has three channels.imageTypeSpecifies how the image data is to be interpreted. Image data is either actual color values (normal), screen colormap indices (screen), or a colormap (colormap). Refer to imp.h for the supported image types.nameSpecifies a descriptive string for the image. Strings longer than IMP_NAME_MAX characters are truncated. Refer to imp.h for the value of IMP_NAME_MAX. If this parameter is specified as NULL, the string "no name" is written into the file. Use the empty string "" to write an empty name string into the image.LBL="" HELPID=""impOpen(), impOpenFd(), impClose(), and impCloseFd() FunctionsID="apenB8"ID="apenB9"ID="apenB10"ID="apenB11"ID="apenB12"ID="apenB13"ID="apenB14"ID="apenB15"impClose() closes a Silicon Graphics image format file previously opened by impOpen() or impOpenFd(). Among other tasks, impClose() closes the file descriptor associated with an image file. If the image was opened using impOpenFd(), the file descriptor specified in that function call is closed by impClose().impCloseFd() performs the same function as impClose(), but it leaves open the file descriptor associated with the image and returns it in the parameter fdp. It then becomes the responsibility of the caller to close the file descriptor when it is no longer needed. It is essential that either impClose() or impCloseFd() be called at the completion of writing a Silicon Graphics image file so that all buffered data can be written and the image header can be updated.Synopsis:#include <imp.h>
int impClose(IMPImage *image);
int impCloseFd(IMPImage *image, int *fdp);Return Value:impOpen() and impOpenFd() return a pointer to an image structure if execution was successful. NULL is returned and IMPerrno is set if an execution error has occurred.impClose() and impCloseFd() return 0 if execution was successful; a -1 is returned and IMPerrno is set if an execution error has occurred.Execution Error Codes:impOpen() and impOpenFd() fail with the following errors:IMP_ERR_READWRITEIMP_ERR_MEMALLOCIMP_ERR_BADMAGICIMP_ERR_BADRASTERIMP_ERR_BADIMAGEIn addition, impOpenFd() fails with the following errors:IMP_ERR_BADFDIMP_ERR_SEEKimpClose() and impCloseFd() fail with the following errors:IMP_ERR_WRITEFLAGIMP_ERR_BADBPPIMP_ERR_BADIMAGENoteThe storage for the IMPImage structure is allocated by the image open function. This storage is deallocated by the impClose() and impCloseFd() functions. The caller should not explicitly reallocate or deallocate any storage related to the image structure.See also:libimp(3), impReadRow(3), impReadRowB(3)LBL="" HELPID=""Data Packing FunctionsID="apenB16"LBL="" HELPID=""impPackRow() and impUnpackRow() FunctionsID="apenB17"ID="apenB18"ID="apenB19"ID="apenB20"Synopsis:#include <imp.h>
void impPackRow(uchar_t *dptr, short *sptr, int n);
void impUnpackRow(short *dptr, uchar_t *sptr, int n);impPackRow() converts the array of short integers pointed to by sptr into the array of unsigned char values pointed to by dptr. Source data that is too large to fit in a character is truncated. For example, the source value 0x0B56 is converted into 0x56 in the destination array. impUnpackRow() converts the array of unsigned char values pointed to by sptr into the array of short integers pointed to by dptr. For example, the source value 0x56 is converted into 0x0056 in the destination array. The parameter n specifies the number of elements in the source and destination arrays.NoteThe allocation of storage for the source and destination arrays is the responsibility of the caller.See also:libimp(3)LBL="" HELPID=""Error Handling FunctionsID="apenB21"LBL="" HELPID=""impPerror() and impErrorString() FunctionsID="apenB22"ID="apenB23"ID="apenB24"ID="apenB25"Synopsis:#include <imp.h>
void impPerror(const char *str);
char* impErrorString(int errCode);
extern int IMPerrno;impPerror() prints error messages to standard error in a format similar to the standard C library function perror(3C). If an error occurs during a libimp function call, the global error variable IMPerrno is set with an error code. The error code is either a system error code (errno) or a libimp-specific code. The symbolic names for the libimp error codes are defined in imp.h. The value of IMPerrno is used by impPerror() as an index to a table of error messages.impPerror() prints user-supplied string str followed by a colon (:), a space, and the error message corresponding to the current value of IMPerrno.If the string str is the NULL string (""), no colon or space is printed, only the error message. The error message is either a system error message or a libimp-specific message. To be of most use, a call to impPerror should be made immediately following the libimp function call where an error has been detected. impErrorString() is similar to the strerror(3C) function and returns the error message corresponding to the error code specified by errCode.If errCode is less than IMP_ERR_BASE, the message returned is a system error message generated by strerror. If errCode is one of the error codes specified in imp.h, the returned string is a libimp-specific error message.See also:libimp(3), perror(3C), strerror(3C)LBL="" HELPID=""Image I/O FunctionsID="apenB26"LBL="" HELPID=""impReadRow(), impReadRowB(), impWriteRow(), and impWriteRowB() FunctionsID="apenB27"ID="apenB28"ID="apenB29"ID="apenB30"ID="apenB31"ID="apenB32"ID="apenB33"ID="apenB34"Synopsis:#include <imp.h>
int impReadRow(IMPImage *image, short *buffer,
ushort_t row, ushort_t channel);
int impReadRowB(IMPImage *image, uchar_t *buffer,
ushort_t row, ushort_t channel);
int impWriteRow(IMPImage *image, short *buffer,
ushort_t row, ushort_t channel);
int impWriteRowB(IMPImage *image, uchar_t *buffer,
ushort_t row, ushort_t channel);impReadRow() and impReadRowB() each read a row of image data from the specified channel of a Silicon Graphics image format file.impReadRow() stores the row data in an array of short integers and can read image data that is one or two bytes per pixel per channel in width. impReadRowB() stores the data in a character array and can handle only image data that is one byte per pixel per channel wide.If impReadRowB() is called to read image data that is two bytes per pixel per channel, an error condition is reported. impWriteRow() and impWriteRowB() each write a row of image data to the specified channel of a Silicon Graphics image file. impWriteRow() writes one or two bytes per pixel per channel image row data. impWriteRowB() writes only one byte per pixel data. It is an error to use impWriteRowB() to write to images that expect two bytes per pixel per channel data.NoteThe functions make use of the following macros:impXSizeReturns the number of pixels in an image file in the X direction.impYSizeReturns the number of pixels in an image file in the Y direction.impNumChannelsReturns the number of color channels in an image. It returns 3 if the image is RGB, 4 if it is CMYK, and 1 if it is monochromeThe functions take the following parameters:imagePointer to an IMPImage structure returned by a call to impOpen() or impOpenFd().bufferCaller-allocated buffer containing the data to write to or to be filled with the data read from the image. The amount of storage allocated for the buffer should be impXSize(image) x sizeof(short) if impReadRow() or impWriteRow() is used, and impXSize(image) if impReadRowB() or impWriteRowB() is used.rowThe image row to read. Rows are numbered from 0 through impYSize(image) minus 1.channelThe image channel to read. Channels are numbered from 0 through impNumChannels(image) minus 1.Return Value:If execution was successful, all functions return the number of pixels (not bytes) read or written. If an execution error occurred, -1 is returned and IMPerrno is set.Execution Error Codes:impWriteRow() and impWriteRowB() fail with the following errors:IMP_ERR_WRITEFLAGIMP_ERR_BADBPPIMP_ERR_BADIMAGEIMP_ERR_SHORTWRITEimpReadRow() and impReadRowB() fail with the following errors:IMP_ERR_READFLAGIMP_ERR_BADBPPIMP_ERR_BADIMAGEIMP_ERR_SHORTREADNoteIt is the caller's responsibility to allocate enough buffer storage for image row data.See also:libimp(3), impOpen(3)LBL="" HELPID=""Color Space Conversion FunctionsID="apenB35"These functions perform color space conversion between a given color space and RGB. The actual transformations performed are described below. Certain functions specify the parameter unity. unity should be set to the value of maximum possible intensity for the arrays specified. For example, if 8-bit data is being converted, unity would be specified as 255. If the data makes use of the full 16 bits available in each array element, unity would be specified as 65535. Note that the parameter n specifies the number of elements in the arrays and not the number of bytes.LBL="" HELPID=""impRGBtoW(), impWtoRGB() FunctionsID="apenB36"ID="apenB37"ID="apenB38"ID="apenB39"IDREF="33015" TYPE="GRAPHIC"Figure B-1 shows the equation for W conversions.FILE="apenB-1.gif" POSITION="INLINE" SCALE="FALSE"LBL="B-1"Figure B-1 ID="33015"W ConversionsSynopsis:#include <imp.h>
void impRGBtoW(short *rbuf, short *gbuf, short *bbuf,
short *wbuf, int n);
void impWtoRGB(short *wbuf, short *rbuf, short *gbuf,
short *bbuf, int n);LBL="" HELPID=""impRGBtoK(), impKtoRGB() FunctionsID="apenB40"ID="apenB41"ID="apenB42"ID="apenB43"IDREF="92505" TYPE="GRAPHIC"Figure B-2 shows the equation for K conversions.FILE="apenB-5.gif" POSITION="INLINE" SCALE="FALSE"LBL="B-2"Figure B-2 ID="92505"K ConversionsSynopsis:#include <imp.h>
void impRGBtoK(short *rbuf, short *gbuf, short *bbuf,
short *kbuf, short unity, int n);
void impKtoRGB(short *kbuf, short *rbuf, short *gbuf,
short *bbuf, short unity, int n);LBL="" HELPID=""impRGBtoCMY(), impCMYtoRGB() FunctionsID="apenB44"ID="apenB45"ID="apenB46"ID="apenB47"IDREF="82113" TYPE="GRAPHIC"Figure B-3 shows the equation for CMY conversions.FILE="apenB-4.gif" POSITION="INLINE" SCALE="FALSE"LBL="B-3"Figure B-3 ID="82113"CMY ConversionsSynopsis:#include <imp.h>
void impRGBtoCMY(short *rbuf, short *gbuf, short *bbuf,
short *cbuf, short *mbuf, short *ybuf,
short unity, int n);
void impCMYtoRGB(short *cbuf, short *mbuf, short *ybuf,
short *rbuf, short *gbuf, short *bbuf,
short unity, int n);LBL="" HELPID=""impRGBtoYIQ(), impYIQtoRGB() FunctionsID="apenB48"ID="apenB49"ID="apenB50"ID="apenB51"IDREF="47125" TYPE="GRAPHIC"Figure B-4 shows the equation for YIQ conversions.FILE="apenB-3.gif" POSITION="INLINE" SCALE="FALSE"LBL="B-4"Figure B-4 ID="47125"YIQ ConversionsSynopsis:#include <imp.h>
void impRGBtoYIQ(short *rbuf, short *gbuf, short *bbuf,
short *ybuf, short *ibuf, short *qbuf,
int n);
void impYIQtoRGB(short *ybuf, short *ibuf, short *qbuf,
short *rbuf, short *gbuf, short *bbuf,
int n);LBL="" HELPID=""impRGBtoYUV(), impYUVtoRGB() FunctionsID="apenB52"ID="apenB53"ID="apenB54"ID="apenB55"IDREF="34666" TYPE="GRAPHIC"Figure B-5 shows the equation for YUV conversions.FILE="apenB-6.gif" POSITION="INLINE" SCALE="FALSE"LBL="B-5"Figure B-5 ID="34666"YUV ConversionsSynopsis:#include <imp.h>
void impRGBtoYUV(short *rbuf, short *gbuf, short *bbuf,
short *ybuf, short *ubuf, short *vbuf,
int n);
void impYUVtoRGB(short *ybuf, short *ubuf, short *vbuf,
short *rbuf, short *gbuf, short *bbuf,
int n);LBL="" HELPID=""impRGBtoYCbCr(), impYCbCrtoRGB() FunctionsID="apenB56"ID="apenB57"ID="apenB58"ID="apenB59"IDREF="58066" TYPE="GRAPHIC"Figure B-6 shows the equation for YCbCr conversions.FILE="apenB-2.gif" POSITION="INLINE" SCALE="FALSE"LBL="B-6"Figure B-6 ID="58066"YCbCr ConversionsSynopsis:#include <imp.h>
void impRGBtoYCbCr(short *rbuf, short *gbuf, short *bbuf,
short *ybuf, short *cbbuf, short *crbuf, int n);
void impYCbCrtoRGB(short *ybuf, short *cbbuf, short *crbuf,
short *rbuf, short *gbuf, short *bbuf, int n);LBL="" HELPID=""impRGBtoCMYK(), impRGBtoDevCMYK(), impCMYKtoRGB() FunctionsID="apenB60"ID="apenB61"ID="apenB62"ID="apenB63"ID="apenB64"ID="apenB65"IDREF="90281" TYPE="GRAPHIC"Figure B-7 shows the equation for CMYK conversions.FILE="apenB-7.gif" POSITION="INLINE" SCALE="FALSE"LBL="B-7"Figure B-7 ID="90281"CMYK ConversionsSynopsis:#include <imp.h>
void impRGBtoCMYK(short *rbuf, short *gbuf, short *bbuf,
short *cbuf, short *mbuf, short *ybug,
short *kbuf, short unity, int n);
void impRGBtoDevCMYK(short *rbuf, short *gbuf, short *bbuf,
short *cbuf, short *mbuf, short *ybug,
short *kbuf, IMPUCRFunc ucr, IMPBGFunc bg,
short unity, int n);
short (*IMPBGFunc)(short k);
short (*IMPUCRFunc)(short k);
void impCMYKtoRGB(short *cbuf, short *mbuf, short *ybuf,
short *kbuf, short *rbuf, short *gbug,
short *bbuf, short unity, int n);LBL="" HELPID=""impRGBtoHSV(), impHSVtoRGB() FunctionsID="apenB66"ID="apenB67"ID="apenB68"Synopsis:#include <imp.h>
void impRGBtoHSV(short *rbuf, short *gbuf, short *bbuf,
short *rbuf, short *gbuf, short *bbuf, int n);LBL="" HELPID=""impRGBtoHLS(), impHLStoRGB() FunctionsID="apenB69"ID="apenB70"ID="apenB71"For HSV conversions, refer to Computer Graphics, Principals and Practice, Foley and Van Dam, 2nd Edition, pages 590-592. For HLS conversions, refer to pages 592-595.Synopsis:#include <imp.h>
void impRGBtoHLS(short *rbuf, short *gbuf, short *bbuf,
short unity, int n);NoteIt is the caller's responsibility to allocate all buffer storage.See Also:libimp(3)LBL="" HELPID=""Math Operation FunctionsLBL="" HELPID=""impZeroRow(), impInitRow(), impCopyRow(), impSAddRow(), impVAddRow(), impSSubRow(), impVSubRow(), impSMulRow(), impSDivRow(), impClampRow() FunctionsID="apenB72"ID="apenB73"ID="apenB74"ID="apenB75"ID="apenB76"ID="apenB77"ID="apenB78"ID="apenB79"ID="apenB80"ID="apenB81"ID="apenB82"ID="apenB83"ID="apenB84"ID="apenB85"ID="apenB86"ID="apenB87"ID="apenB88"ID="apenB89"ID="apenB90"ID="apenB91"Synopsis:#include <imp.h>
void impZeroRow(short *dptr, int n);
void impInitRow(short *dptr, int val, int n);
void impCopyRow(short *dptr, short *sptr, int n);
void impSAddRow(short *dptr, short *sptr, int val, int n);
void impVAddRow(short *dptr, short *sptr1, short *sptr2, int n);
void impSSubRow(short *dptr, short *sptr, int val, int n);
void impVSubRow(short *dptr, short *sptr1, short *sptr2, int n);
void impSMulRow(short *dptr, short *sptr, int val, int n);
void impSDivRow(short *dptr, short *sptr, int val, int n);
void impClampRow(short *dptr, short *sptr, int lov, int hiv, int n);In the following descriptions, the parameter n specifies the number of elements in an array and not the number of bytes in the array. In addition, functions that take a source array pointer and a destination array pointer can specify the same array as both a source and destination.impZeroRowInitializes to zero the array pointed to by dptr.impInitRowInitializes the array dptr to the value val.impCopyRowCopies the array sptr to the array dptr.impSAddRowAdds the value val to each element of the array sptr and stores the result in the array dptr.impVAddRowAdds the corresponding elements of sptr1 and sptr2 and stores the result in the array dptr.impSSubRowSubtracts the value val from each element of the array sptr and stores the result in the array dptr.impVSubRowSubtracts the corresponding elements of sptr2 from those of sptr1 and stores the result in the array dptr.impSMulRowMultiplies each element of the array sptr by val and stores the result in dptr.impSDivRowDivides each element of the array sptr by val and stores the result in dptr.impClampRowClamps the values of the array sptr between the values lov and hiv inclusive. The result is stored in the array dptr.NoteIt is the caller's responsibility to allocate all buffer storage. Also, because the arrays referenced by these functions are short integer arrays, the caller should be aware of overflow/wraparound conditions.See also:libimp(3)LBL="" HELPID=""Zooming FunctionsID="apenB92"LBL="" HELPID=""impCreateZoom(), impDestroyZoom(), impResetZoom(), impZoomRow() FunctionsID="apenB93"ID="apenB94"ID="apenB95"ID="apenB96"ID="apenB97"ID="apenB98"ID="apenB99"ID="apenB100"Synopsis:#include <imp.h>
ushort_t row, void *clientData);The ID="apenB101"libimp library provides an API for performing image resizing or zooming. Images can be zoomed up or down using any of a number of resampling methods. The resampling methods divide into two categories. The first resampling category is non-filtered zooming (also known as replicative zoom, decimation). The second resampling category is filtered zooming where a filter of a given shape is applied to the data. The image zooming is performed on a row-by-row basis using a one-pass, two-dimensional convolution.To zoom one or more rows of an image, first create a zoom operator by calling ID="apenB102"impCreateZoom(). One of the parameters to impCreateZoom() is a pointer to a function that is called during the zoom to read rows of the source image. To obtain zoomed rows, call impZoomRow()ID="apenB103". When all desired zoomed rows have been obtained, call impDestroyZoom()ID="apenB104" to deallocate storage held by the zoom operator. When filtered zooming is performed, a number of contiguous rows of image data are cached. Often all rows of a given image channel are zoomed, followed by all rows of the next channel. Since rows are cached, the cache should be flushed when switching between image channels. The ID="apenB105"impResetZoom() function performs this row cache flushing operation.The impCreateZoom() function has the following parameters:srcXSize, srcYSizeWidth and height of the source image in pixels.dstXSize, dstYSizeWidth and height of the destination (that is, zoomed) image in pixels.readRowFuncPointer to a function that is called to read a row from the source image. The prototype for this function isint (*IMPReadRowFunc)(short *buffer,
ushort_t row,
void *clientData);The function should read the image row indicated by row and place the data in buffer. The storage for buffer is allocated and deallocated by the zoom operator and should not be manipulated by the read row function. clientData is a pointer to caller-specific information. The caller may specify a pointer to client data when calling the impZoomRow() function. That pointer is passed to the read row function.At the caller's discretion, this pointer may be set to NULL. A common use of the client data is to pass a pointer to a structure containing the image structure pointer and the channel number. The read row function must return -1 if it encounters an error while obtaining the row data and must return a value of 0 or greater if the function succeeds.numChannelsSpecifies the number of channels of image data that are packed on a single row. For example, if each row contains data for only a single channel, then numChannels should be specified as one. However, if each row contains RGB data packed together as RGBRGBRGB..., numChannels should be specified as three.filterTypeSpecifies the type of filter to be used for resampling the image during zooming.The filter types available areCOLUMNS="2"LEFT="0" WIDTH="77"Filter TypeLEFT="85" WIDTH="72"CategoryLEFT="0" WIDTH="77"IMPImpulseLEFT="85" WIDTH="72"ReplicativeLEFT="0" WIDTH="77"IMPBoxLEFT="85" WIDTH="72"FilteredLEFT="0" WIDTH="77"IMPTriangleLEFT="85" WIDTH="72"FilteredLEFT="0" WIDTH="77"IMPQuadraticLEFT="85" WIDTH="72"FilteredLEFT="0" WIDTH="77"IMPMitchellLEFT="85" WIDTH="72"FilteredLEFT="0" WIDTH="77"IMPGaussianLEFT="85" WIDTH="72"FilteredRefer to IDREF="79580" TYPE="TITLE""Filter Functions" for detailed information on the available filters.blurFactorSpecifies a multiplier for the width of the filter. The default blur factor is 1.0. Higher factors increase the amount of blur present in the image.The impZoomRow() function has the following parameters:zoomPointer to a zoom operator structure obtained from a call to impCreateZoom().bufferCaller-allocated buffer that is filled with the zoomed image row data. The buffer should be allocated to accommodated dstXSize * numChannels * sizeof(short) bytes.rowThe desired zoomed row. Rows are numbered from 0 through dstYSize minus 1. clientData is a pointer to client data. This pointer is passed to the readRowFunc. A typical use of this is for passing a pointer to a structure containing the IMPImage pointer and the channel number.LBL="" HELPID=""ID="79580"Filter FunctionsID="apenB106"The resampling filters available for zooming are summarized below. Note that the span of the filter (x range) is expressed in terms of the original image, not the zoomed image. IDREF="61054" TYPE="TABLE"Table B-3 lists the available filter functions.COLUMNS="3"LBL="B-3"Table B-3 (continued) ID="61054"Filter FunctionsLEFT="0" WIDTH="99"Filter TypeLEFT="105" WIDTH="122"FunctionLEFT="235" WIDTH="110"SpanLEFT="0" WIDTH="99"IMPImpulseLEFT="105" WIDTH="122"Not ApplicableLEFT="235" WIDTH="110"LEFT="0" WIDTH="99"IMPBoxLEFT="105" WIDTH="122"f(x) = 0.0LEFT="235" WIDTH="110"x < -0.5LEFT="0" WIDTH="99"LEFT="105" WIDTH="122"f(x) = 1.0LEFT="235" WIDTH="110"-0.5 <= x < 0.5LEFT="0" WIDTH="99"LEFT="105" WIDTH="122"f(x) = 0.0LEFT="235" WIDTH="110"x >= 0.5LEFT="0" WIDTH="99"IMPTriangleLEFT="105" WIDTH="122"f(x) = 0.0LEFT="235" WIDTH="110"x < -1.0LEFT="0" WIDTH="99"LEFT="105" WIDTH="122"f(x) = 1.0+xLEFT="235" WIDTH="110"-1.0 <= x < 0.0LEFT="0" WIDTH="99"LEFT="105" WIDTH="122"f(x) = 1.0-xLEFT="235" WIDTH="110"0.0 <= x < 1.0LEFT="0" WIDTH="99"LEFT="105" WIDTH="122"f(x) = 0.0LEFT="235" WIDTH="110"x >= 1.0LEFT="0" WIDTH="99"IMPQuadraticLEFT="105" WIDTH="122"f(x) = 0.0LEFT="235" WIDTH="110"x < -1.5LEFT="0" WIDTH="99"LEFT="105" WIDTH="122"f(x) = 0.5*(x+1.5)^2LEFT="235" WIDTH="110"-1.5 <= x < -0.5LEFT="0" WIDTH="99"LEFT="105" WIDTH="122"f(x) = 0.75-x^2LEFT="235" WIDTH="110"-0.5 <= x < 0.5LEFT="0" WIDTH="99"LEFT="105" WIDTH="122"f(x) = 0.5*(x-1.5)^2LEFT="235" WIDTH="110"0.5 <= x < 1.5LEFT="0" WIDTH="99"LEFT="105" WIDTH="122"f(x) = 0.0LEFT="235" WIDTH="110"x >= 1.5LEFT="0" WIDTH="99"IMPMitchellLEFT="105" WIDTH="122"b = 1.0/3.0LEFT="235" WIDTH="110"LEFT="0" WIDTH="99"LEFT="105" WIDTH="122"c = 1.0/3.0LEFT="235" WIDTH="110"LEFT="0" WIDTH="99"LEFT="105" WIDTH="122"p0 = (6.0-2.0*b)/6.0LEFT="235" WIDTH="110"LEFT="0" WIDTH="99"LEFT="105" WIDTH="122"p2 = (-18.0+12.0*b+6.0*c)/6.0LEFT="235" WIDTH="110"LEFT="0" WIDTH="99"LEFT="105" WIDTH="122"p3 = (12.0-9.0*b-6.0*c)/6.0LEFT="235" WIDTH="110"LEFT="0" WIDTH="99"LEFT="105" WIDTH="122"q0 = (8.0*b+24.0*c)/6.0LEFT="235" WIDTH="110"LEFT="0" WIDTH="99"LEFT="105" WIDTH="122"q1 = (-12.0*b-48.0*c)/6.0LEFT="235" WIDTH="110"LEFT="0" WIDTH="99"LEFT="105" WIDTH="122"q2 = (6.0*b+30.0*c)/6.0LEFT="235" WIDTH="110"LEFT="0" WIDTH="99"LEFT="105" WIDTH="122"q3 = (-b-6.0*c)/6.0LEFT="235" WIDTH="110"LEFT="0" WIDTH="99"LEFT="105" WIDTH="122"f(x) = 0.0LEFT="235" WIDTH="110"x < -2.0LEFT="0" WIDTH="99"LEFT="105" WIDTH="122"f(x) = q0-x*(q1-x*(q2-x*q3))LEFT="235" WIDTH="110"-2.0 <= x < -1.0LEFT="0" WIDTH="99"LEFT="105" WIDTH="122"f(x) = p0+x*x*(p2-x*p3)LEFT="235" WIDTH="110"-1.0 <= x < 0.0LEFT="0" WIDTH="99"LEFT="105" WIDTH="122"f(x) = p0+x*x*(p2+x*p3)LEFT="235" WIDTH="110"0.0 <= x < 1.0LEFT="0" WIDTH="99"LEFT="105" WIDTH="122"f(x) = q0+x*(q1+x*(q2+x*q3))LEFT="235" WIDTH="110"1.0 <= x < 2.0LEFT="0" WIDTH="99"LEFT="105" WIDTH="122"f(x) = 0.0LEFT="235" WIDTH="110"x >= 2.0LEFT="0" WIDTH="99"IMPGaussianLEFT="105" WIDTH="122"a(x) = 1.0/exp((1.5*x)^2)LEFT="235" WIDTH="110"LEFT="0" WIDTH="99"LEFT="105" WIDTH="122"b(x) = 1.0/exp(1.5^4)LEFT="235" WIDTH="110"LEFT="0" WIDTH="99"LEFT="105" WIDTH="122"f(x) = a(x)-b(x)LEFT="235" WIDTH="110"Return Value:The impCreateZoom() function returns a pointer to a zoom operator structure if execution was successful. NULL is returned and IMPerrno is set if an execution error has occurred.The impZoomRow() function returns 0 if execution was successful. -1 is returned and IMPerrno is set if an execution error occurred.Execution Error Codes:The impCreateZoom() function fails with the following error:IMP_ERR_MEMALLOCThe impZoomRow() function fails with the following error:IMP_ERR_READROWNoteThe storage for the IMPZoom structure is allocated by the zoom operator creation function. This storage is deallocated by the impDestroyZoom() function. The caller should not explicitly reallocate or deallocate any storage related to the image structure. Furthermore, the fields of the IMPZoom structure are private and should not be modified by the caller.See also:libimp(3)LBL="C"ID="64689"Printer Object Database (POD) File FormatsID="apenC1"This appendix describes the file formats of the ASCII text files that compose the printer object database (POD).The following major topics are discussed:IDREF="24663" TYPE="TITLE""General Syntax"IDREF="46898" TYPE="TITLE""Input Parsing Rules for libpod Files"IDREF="25256" TYPE="TITLE""Printer Configuration File Format"IDREF="76658" TYPE="TITLE""Printer Status File Format"IDREF="62827" TYPE="TITLE""Printer Log File Format"LBL="" HELPID=""OverviewThe printer object database (POD) contains information on the current configuration, status, and job history of a single printer. Each printer that is physically installed on a system must maintain its own POD. To maintain network-transparent, mediated access to the POD files, all interaction between the printer driver and POD files must be through the libpod API. For additional information, see IDREF="65271" TYPE="TITLE""The libpod Library" in Chapter 6 and the libpod(3) reference page.The initial set of POD files created by the printer driver developer and installed on the host server system must include the following:<printer name>.config: a configuration file representing the printer's capabilities<printer name>.stats: a status file indicating a typical printing state<printer name>.log: an empty log fileThe name of each POD file is formed from the printer name and the suffix .config, .status, or .log, respectively. Note that the printer name must be the same as the name of the printer model file. All POD files are copied from the template POD files and installed in the appropriate directory.The information contained in each POD file is summarized below and explained in detail in subsequent sections.LBL="" HELPID=""Printer Configuration FileID="apenC2"The printer configuration file (<printer name>.config) contains detailed information on the printer's capabilities. The file is created by the printer driver developer to characterize the printer's capabilities. The possible paper sizes, printer location, and available fonts are all specified in this file. Typically the information in the config file does not change over time. Printer filters and drivers treat it as a read-only file. The printer install tools may modify the file at printer installation time to enter site-specific data, such as printer location, or note the presence of optional equipment, such as a duplex option or an envelope feeder.LBL="" HELPID=""Printer Status FileID="apenC3"The printer status file (<printer name>.status) contains information about the current operational status of the printer. The information in the file indicates whether the printer is busy, what type of printing media is installed, and so on. The contents of this file change during every print job. The driver developer provides an initial copy of the status file, but it is the job of the printer driver to update the file. Printer filter programs normally treat this file as if it were a read-only file.LBL="" HELPID=""Printer Log FileID="apenC4"The printer log file (<printer name>.log) contains the print job history for the printer. Information for old jobs as well as the current print job is maintained. Typically, printer filters and drivers append information to the log file, while general applications treat the file as if it were a read-only file.LBL="" HELPID=""ID="24663"General SyntaxID="apenC5"ID="apenC6"LBL="" HELPID=""ID="13460"Character SetID="apenC7"<space>: 0x09, 0x20 (<sp>, <ht>)
<array>: <string> [[<separator> <string>]...]LBL="" HELPID=""ID="46898"Input Parsing Rules for libpod FilesID="apenC9"ID="apenC10"ID="apenC11"The following rules apply when a POD file is parsed by the libpod API:All <null> characters are ignored. Their use is discouraged to avoid errors caused by nonprinting characters appearing in the POD files.All input lines are truncated to PD_STR_MAX-1, not counting <null> characters and <endline>, which are removed on input. The value of PD_STR_MAX is defined in the header file /usr/include/pod.h.All occurrences of <white> sequences are reduced to a single <sp> character. Any <white> at the beginning or end of a field is removed.There are no quoted strings. Quotation marks are treated like any other characters and cannot be used to force additional <white> into a field.All fields are checked for correct syntax based on entry type. Failure to provide information in the correct format results in improper parsing.When scanning for <int> or <float> numbers within a field, all characters that are not valid within an <int> or <float> are treated as <white> (in the case of an <int>, <sign> and <point> are treated as <white>). This allows characters to be inserted to improve readability. For example, the following are equivalent if two <int> items are expected:300 300300 x 300300 by 300300,300Entries containing no characters other than <white> before the first <separator> or <endline> are treated as null entries and discarded without error. These lines may be used as comments by placing a <separator> before any other information.Blank lines are ignored and may be inserted to improve readability.<keyfield> matching is done in a case-independent manner.Fields designed to be human-readable are not modified, except to remove <null> and excess <white>. Case and all <plainchar> sequences are preserved.A <keyfield> may require a long list of items (for example, Available Fonts). To improve readability and avoid the risk of input line buffer overflow (see the second bullet item above), a <keyfield> may be repeated.For example, a list of fifty Available Fonts items may be broken into two Available Fonts entries with 25 items each. The overall number of items that can be specified in a list is limited only by available system memory resources.There is no required entry order. The <keyfield> entries may appear in any order within a POD file.Default values are assumed for certain fields if values are not specified. The values of these defaults should not be relied upon and may change in future releases.LBL="" HELPID=""ID="25256"Printer Configuration File FormatID="apenC12"This section describes the format of the printer configuration file. The configuration file is installed by the printer install tools with the name <printer name>.config.LBL="" HELPID=""General FormatThe format for an entry in the configuration file is<keyfield> <separator> [<infofield>] <endline>where<keyfield>is one of the reserved fields described in the "Key Field" column of IDREF="74833" TYPE="TABLE"Table C-1.<separator>is the "separator" character defined in IDREF="13460" TYPE="TITLE""Character Set".<infofield>is one or more of the options specified in the "Info Field Type" column of IDREF="74833" TYPE="TABLE"Table C-1.<endline>is one of the "endline" characters defined in IDREF="13460" TYPE="TITLE""Character Set".LBL="" HELPID=""Config File OptionsAll entries in the config file are optional. Entries that are not provided or that have no <infofield> specified are assigned default values. However, since printer capabilities differ, it is strongly recommended that no entries be omitted. The defaults should not be relied on, as they may change in future releases. IDREF="74833" TYPE="TABLE"Table C-1 lists the config file options in alphabetical order. A detailed explanation of each option follows the table.COLUMNS="3"LBL="C-1"Table C-1 (continued) ID="74833" Config File OptionsLEFT="0" WIDTH="90"Key FieldLEFT="95" WIDTH="126"Info Field TypeLEFT="230" WIDTH="153"DefaultLEFT="0" WIDTH="90"Active Status PathLEFT="95" WIDTH="126"<word>LEFT="230" WIDTH="153"See IDREF="98330" TYPE="TITLE""Active Status Path".LEFT="0" WIDTH="90"Available FontsLEFT="95" WIDTH="126"<array>LEFT="230" WIDTH="153"(0 elements)LEFT="0" WIDTH="90"Black SubstituteLEFT="95" WIDTH="126"<keyword>LEFT="230" WIDTH="153"NoLEFT="0" WIDTH="90"Color AdjustmentLEFT="95" WIDTH="126"<array>LEFT="230" WIDTH="153"(0 elements)LEFT="0" WIDTH="90"Cost per PageLEFT="95" WIDTH="126"<float>LEFT="230" WIDTH="153"0.00LEFT="0" WIDTH="90"Default CALEFT="95" WIDTH="126"<int>LEFT="230" WIDTH="153"0LEFT="0" WIDTH="90"Default ISLEFT="95" WIDTH="126"<int> [,gamma=<float>]LEFT="230" WIDTH="153"0, gamma=-1.0LEFT="0" WIDTH="90"Default MTLEFT="95" WIDTH="126"<int>LEFT="230" WIDTH="153"0LEFT="0" WIDTH="90"Default QMLEFT="95" WIDTH="126"<int>LEFT="230" WIDTH="153"0LEFT="0" WIDTH="90"Driver PathLEFT="95" WIDTH="126"<word>LEFT="230" WIDTH="153"See IDREF="15206" TYPE="TITLE""Driver Path".LEFT="0" WIDTH="90"Error Retry WaitLEFT="95" WIDTH="126"<int>LEFT="230" WIDTH="153"10 secondsLEFT="0" WIDTH="90"Input SourceLEFT="95" WIDTH="126"<array>LEFT="230" WIDTH="153"(0 elements)LEFT="0" WIDTH="90"Location CodeLEFT="95" WIDTH="126"<keyword>LEFT="230" WIDTH="153"NoneLEFT="0" WIDTH="90"Manual CapableLEFT="95" WIDTH="126"<keyword>LEFT="230" WIDTH="153"NoLEFT="0" WIDTH="90"Maximum AddrLEFT="95" WIDTH="126"<Maximum Addrint> <int>LEFT="230" WIDTH="153"See IDREF="98889" TYPE="TITLE""Minimum Addr".LEFT="0" WIDTH="90"Maximum Print AreaLEFT="95" WIDTH="126"<float> <float>LEFT="230" WIDTH="153"See IDREF="97499" TYPE="TITLE""Maximum Print Area".LEFT="0" WIDTH="90"Media StandardLEFT="95" WIDTH="126"<keyword>LEFT="230" WIDTH="153"AmericanLEFT="0" WIDTH="90"Media TypeLEFT="95" WIDTH="126"<array>LEFT="230" WIDTH="153"(0 elements)LEFT="0" WIDTH="90"Media WaitLEFT="95" WIDTH="126"<int>LEFT="230" WIDTH="153"300 secondsLEFT="0" WIDTH="90"Minimum AddrLEFT="95" WIDTH="126"<int> <int>LEFT="230" WIDTH="153"See IDREF="52265" TYPE="TITLE""Minimum Print Area".LEFT="0" WIDTH="90"Minimum Print AreaLEFT="95" WIDTH="126"<float> <float>LEFT="230" WIDTH="153"See IDREF="52265" TYPE="TITLE""Minimum Print Area".LEFT="0" WIDTH="90"Number of ColorsLEFT="95" WIDTH="126"<int> [<int>]LEFT="230" WIDTH="153"1 1LEFT="0" WIDTH="90"Physical LocationLEFT="95" WIDTH="126"<string>LEFT="230" WIDTH="153"UnknownLEFT="0" WIDTH="90"Port PathLEFT="95" WIDTH="126"<word>LEFT="230" WIDTH="153"/dev/nullLEFT="0" WIDTH="90"Printer ClassLEFT="95" WIDTH="126"<keyword>LEFT="230" WIDTH="153"DumbLEFT="0" WIDTH="90"Printer ModelLEFT="95" WIDTH="126"<string>LEFT="230" WIDTH="153"UnknownLEFT="0" WIDTH="90"Printer OptionsLEFT="95" WIDTH="126"<string>LEFT="230" WIDTH="153"(empty string)LEFT="0" WIDTH="90"Quality ModesLEFT="95" WIDTH="126"<array>LEFT="230" WIDTH="153"(0 elements)LEFT="0" WIDTH="90"ResolutionLEFT="95" WIDTH="126"<int> <int>LEFT="230" WIDTH="153"300 dpi 300 dpiLEFT="0" WIDTH="90"Size Table EntryLEFT="95" WIDTH="126"<sizeentry>LEFT="230" WIDTH="153"See IDREF="24071" TYPE="TITLE""Size Table Entry".LEFT="0" WIDTH="90"Status Update WaitLEFT="95" WIDTH="126"<int>LEFT="230" WIDTH="153"300 secondsLEFT="0" WIDTH="90"TechnologyLEFT="95" WIDTH="126"<string>LEFT="230" WIDTH="153"UnknownLEFT="0" WIDTH="90"Time per PageLEFT="95" WIDTH="126"<int> [<int>]LEFT="230" WIDTH="153"0 0LBL="" HELPID=""ID="98330"Active Status PathID="apenC13"ID="apenC14"Active Status Path is the full pathname of the POD status file. The value of this entry is not used by the libpod API. The value of this entry is always set by the API to PDpod_path/<printer name>.status. Refer to the libpod(3) reference page for additional information.LBL="" HELPID=""Available FontsID="apenC15"ID="apenC16"The Available Fonts option contains a list of font names representing the fonts available on the printer. For printers with built-in PostScript interpreters, this list should include only those fonts built into the printer (typically a set of 35 standard fonts). The default value is 0 elements.For raster printers, the PostScript interpretation is performed on the printer host machine. Thus, the fonts listed for these printers should correspond to the names of the font outline files installed on the printer host. There are two methods for specifying the font names: the names can be listed individually or a full path to the directory where the outline fonts are stored can be specified. The two methods can be mixed. When a path is specified, the names of the files in that directory are assumed to be the names of the fonts. To exclude filenames from the directory, specify the names of the files to be excluded with a leading "!". The filenames to be excluded must appear on the same line as the directory containing the filename to be excluded. The following is a valid Available Fonts list:NewYearRoman | /usr/lib/DPS/outline/base | !fonts.dirThis entry indicates that the only font available on the printer is NewYearRoman, and all file names are in the directory /usr/lib/DPS/outline/base with the exception of fonts.dir. Note that font names must not contain any white space.Starting with Impressario 2.0, a new logical AND operator, &, is available for font lists. It allows the list of fonts on the printer to be logically AND'ed with the list of fonts on the print server, generating a list of fonts that are common to both. The common list is needed for the text2ps(1) filter, which uses the font metric information from the print server fonts to determine where line and page breaks should be made. The AND operator is intended for use by printer drivers that send PostScript directly to the printer.The entry below says that NewYearRoman is available on the printer, and if it is also available in /usr/lib/DPS/outline/base, it should be on the list of available fonts when a printer driver is installed:| NewYearRoman | &/usr/lib/DPS/outline/baseFor another example, see the file/usr/lib/print/data/lexmarkoptra_model.configLBL="" HELPID=""Black SubstituteID="apenC17"ID="apenC18"The Black Substitute option is either yes, indicating that the printer should by default substitute true black for composite black, or no, indicating that it should not. The default value is no.LBL="" HELPID=""Color AdjustmentID="apenC19"ID="apenC20"The Color Adjustment option is a list of color adjustment methods available for the printer. The color adjustment methods perform color correction between the current input source and the printer. An example entry isNone | Fix Blue | Gamma CorrectThe default value is 0 elements.Starting with Impressario 2.0, International Color Consortium (ICC) color profiles and various filters, such as cocostiff, are used to perform color management. Color correction is applied as a filter before the driver is invoked (FTR rules have been added so fileconvert will invoke the correct filters based on the file type). The Color Adjustment entry in the POD file is currently not used. See IDREF="67009" TYPE="TITLE"Appendix G for more information on color management in Impressario.LBL="" HELPID=""Cost per PageID="apenC21"ID="apenC22"The Cost per Page option is the cost per printed page in local currency. For example, 0.50 for 50 cents per page. The default value is 0.00.LBL="" HELPID=""Default CAID="apenC23"ID="apenC24"The Default CA option is the index to the Color Adjustment list indicating the default adjustment method. This index is based at one rather than zero. Thus, the first method in the list is at position 1, the second at 2, and so on. If there are no adjustment methods specified, this entry should either be left empty or set to 0. The default value is 0.LBL="" HELPID=""Default ISID="apenC25"ID="apenC26"Default IS is the index to the Input Source list indicating the default input source. This index is based at one rather than zero. Thus, the first source in the list is at position 1, the second at 2, and so on. If there are no input sources specified, this entry should either be left empty or set to 0.When used for printer color correction, this entry can also be used to specify the default device's gamma correction value. The gamma value is specified after the default input source index, as in the following example:1, gamma = 1.0LBL="" HELPID=""Default MTID="apenC27"ID="apenC28"Default MT is the index to the Media Type list indicating the default media. This index is based at one rather than zero. Thus, the first media in the list is at position 1, the second at 2, and so on. If there are no media types listed, this entry should either be left empty or set to 0. The default value is 0.LBL="" HELPID=""Default QMID="apenC29"ID="apenC30"Default QM is the index to the Quality Modes list indicating the default quality mode. This index is based at one rather than zero. Thus, the first quality mode in the list is at position 1, the second at 2, and so on. If there are no quality modes specified, this entry should either be left empty or set to 0. The default value is 0.LBL="" HELPID=""ID="15206"Driver PathID="apenC31"ID="apenC32"Driver Path is the full pathname of the installed printer driver. The default is the full pathname of the POD config file, with the suffix .config removed.LBL="" HELPID=""Error Retry WaitID="apenC33"ID="apenC34"Error Retry Wait refers to the number of seconds to wait after an error has occurred before attempting to resume printing. The default is 10 seconds.LBL="" HELPID=""Input SourceID="apenC35"ID="apenC36"Input Source is a list of printer input sources. The primary use of this entry is to list the image source devices that have been characterized for printer color correction. A common input device is the monitor. An example entry is Sony 16" Monitor.LBL="" HELPID=""Location CodeID="apenC37"ID="apenC38"The Location Code option is used to supply a site-specific keyword that identifies the printer's physical location. For example, 3U-924. There is no default value. This code should be machine-readable and -sortable for use by a location-querying browser.LBL="" HELPID=""Manual CapableID="apenC39"ID="apenC40"Manual Capable is either yes, indicating that the printer is capable of being manually fed, or no, indicating that it is not. The default value is no. This value should be set to yes only if the printer supports the -m option (see IDREF="77047" TYPE="TITLE""The Filter/Driver Specification and psrip" in Chapter 3).LBL="" HELPID=""ID="29020"Maximum AddrID="apenC41"ID="apenC42"Maximum Addr is the maximum printable area dimensions expressed in dots. The default values for this entry assume an A-size page (8.5 by 11.0 inches) in portrait orientation with 0.5-inch margins. At 300 dpi, this gives a printable area of 2250 by 3000 dots. The minimum and maximum values are identical in the default case. If a Page Size Table has been specified, the values for this entry are derived from it. Also see IDREF="98889" TYPE="TITLE""Minimum Addr."LBL="" HELPID=""ID="97499"Maximum Print AreaID="apenC43"ID="apenC44"Maximum Print Area is the maximum printable area dimensions expressed in inches. The default values for this entry assume an A-size page (8.5 by 11.0 inches) in portrait orientation with 0.5-inch margins. This gives a printable area of 7.5 by 10.0 inches. The minimum and maximum values are identical in the default case. If a Page Size Table has been specified, the values for this entry are derived from it. Also see IDREF="52265" TYPE="TITLE""Minimum Print Area."LBL="" HELPID=""Media StandardID="apenC45"ID="apenC46"Media Standard indicates the paper measurement standard. Keywords are American and Metric. The default value is American.LBL="" HELPID=""Media TypeID="apenC47"ID="apenC48"Media Type is an array that contains the output media types supported by the printer. Typical items are Bond Paper and Transparency Film. The default array has 0 elements.LBL="" HELPID=""Media WaitID="apenC49"ID="apenC50"Media Wait is the number of seconds to wait for manual feed or print media changes before the default media source is used. The default is 300 seconds.LBL="" HELPID=""ID="98889"Minimum AddrID="apenC51"ID="apenC52"Minimum Addr is the minimum printable area dimensions expressed in dots. The default values for this entry assumes an A-size page (8.5 by 11.0 inches) in portrait orientation with 0.5-inch margins. At 300 dpi, this gives a printable area of 2250 by 3000 dots. The minimum and maximum values are identical in the default case. If a Page Size Table has been specified, the values for this entry are derived from it. Also see IDREF="29020" TYPE="TITLE""Maximum Addr."LBL="" HELPID=""ID="52265"Minimum Print AreaID="apenC53"ID="apenC54"Minimum Print Area is the minimum printable area dimensions expressed in inches. The default values for this entry assume an A-size page (8.5 by 11.0 inches) in portrait orientation with 0.5-inch margins. This gives a printable area of 7.5 by 10.0 inches. The minimum and maximum values are identical in the default case. If a Page Size Table has been specified, the values for this entry are derived from it. Also see IDREF="97499" TYPE="TITLE""Maximum Print Area."LBL="" HELPID=""Number of ColorsID="apenC55"ID="apenC56"Number of Colors is the minimum or, optionally, maximum number of colors that are available on the printer. If the maximum number of colors is not provided, it is assumed to be the same as the minimum. A monochrome printer or printer ribbon provides one color. A CMY printer or ribbon provides three colors.Note that this field should contain only the number of colors available on the printer. The colorspace, depth, and data format are provided in the Number of Colors entry in the status file. The default value is 1.LBL="" HELPID=""Physical LocationID="apenC57"ID="apenC58"Physical Location is the human-readable description of the printer's physical location. For example, Bldg. 3 Upper, Room 924. The default value is Unknown.LBL="" HELPID=""Port PathID="apenC59"ID="apenC60"Port Path is the full pathname of the I/O port to which the printer is physically connected. For example, /dev/plp for a parallel printer, /dev/ttyd2 for a serial printer, and /dev/scsi/sc0d6l0 for a SCSI printer. The default value is /dev/null.LBL="" HELPID=""Printer ClassID="apenC61"ID="apenC62"The Printer Class entry is used to specify the class of printer being used. Available values are Dumb, Raster, ColorRaster, MonoPostScript, ColorPostScript, and Plotter. The following printer classes are obsolete and should not be used for new development: DumbColor, PostScript, and Color. The default value is Dumb.LBL="" HELPID=""Printer ModelID="apenC63"ID="apenC64"The Printer Model entry is a keyword that is the manufacturer's description of the printer. For example, Tektronix Phaser II SX or Apple LaserWriter II NTX. The default value is Unknown.LBL="" HELPID=""Printer OptionsID="apenC65"ID="apenC66"Printer Options describe the standard installed printer optional equipment. For example, 8 megabytes RAM. The default is an empty string.LBL="" HELPID=""Quality ModesID="apenC67"ID="apenC68"Quality Modes is a list of output quality modes available on the printer. For example, draft and letter. The default value is 0 elements.LBL="" HELPID=""ResolutionID="apenC69"ID="apenC70"Resolution is the horizontal or vertical printer resolution in dots per inch (dpi). For printers that allow multiple resolutions, the status file Printer Options entry should be parsed for the CurrentRes keyword. This keyword indicates the current printer resolution. If the keyword is not found, the config file Resolution entry should be used. The default values are both 300 dots per inch.LBL="" HELPID=""ID="24071"Size Table EntryID="apenC71"ID="apenC72"The Size Table Entry<infofield> has the format <sizeentry> defined as<sizeentry>: <keyword> <int> <int> <float> <float> <float>
<float> [<hbyte> [<hbyte>]]Size Table Entry describes a particular media size that is supported by the printer. Typically, there is one Size Table Entry per supported media size (for example, an entry each for A size and B size), although it is acceptable to have multiple entries for a paper size if multiple resolutions or ribbons are supported. The media size entry has seven required fields and two optional fields. All fields are separated by white space.The first required field contains the Media Size (for example, A). The list of possible media sizes can be found in the file /usr/include/pod.h. The media size keyword is simply the media size listed in pod.h with the PD_SIZE_ prefix removed. The size names listed in pod.h with the suffix _LAND indicate landscape orientation and should not be used as media size keywords. Media with landscape orientation is indicated by the width and height fields of the size table entry.The next two fields are the media-imageable width and height expressed in dots. Typically, the imageable dimensions are derived by subtracting the margins from the total media size and converting the result to dots.The next two fields are the overall media width and height expressed in inches.The last two required fields are the left and top margins expressed in inches.The first optional field specifies the printing raster direction. Refer to pod.h for the values that may be specified in this field.The second optional field is the media validation mask. This mask can be used to differentiate among media entries that have the same media name but differ in other respects (for example, resolution). The field is a bit mask and so, to fully differentiate among similar entries, the values must be powers of two. Refer to the PDReadInfo(3) reference page for more information on the use of this field.A default Size Table Entry is always added to the end of the table when it is read by libpod. This default entry isA 2250 3000 8.500 11.000 0.500 0.500 0x00 0xFFLBL="" HELPID=""Status Update WaitID="apenC73"ID="apenC74"Status Update Wait is the number of seconds to wait between updates of the POD status file when no error has occurred. The default is 300 seconds.LBL="" HELPID=""TechnologyID="apenC75"ID="apenC76"The Technology option indicates the type of printing technology used in the printer. For example, ink jet, wax transfer, dye sublimation, and color laser. The default value is Unknown.LBL="" HELPID=""Time per PageID="apenC77"ID="apenC78"Time per Page is the average and, optionally, maximum time to print a page, in seconds. If the maximum time is not provided, it is assumed to be the same as the average time. The default values are both 0.LBL="" HELPID=""ID="76658"Printer Status File FormatID="apenC79"ID="apenC80"This section describes the format of the printer status file. The status file is installed by the printer install tools with the name <printer name>.status.LBL="" HELPID=""General FormatID="apenC81"The format for an entry in the printer status file is<keyfield> <separator> [<infofield>] <endline>where<infofield>is the parameter is specified by IDREF="94365" TYPE="TABLE"Table C-2.<separator>is the separator defined in IDREF="13460" TYPE="TITLE""Character Set".<endline>is one of the endline characters defined in IDREF="13460" TYPE="TITLE""Character Set".LBL="" HELPID=""Printer Status File EntriesID="apenC82"All entries in the status file are optional. Entries that are not provided or that have no <infofield> are assigned default values. However, since the status file is the only means to indicate printer status to the user, it is strongly suggested that a complete status file be provided by the developer and that the printer driver update the status file to reflect the printer's current status.IDREF="94365" TYPE="TABLE"Table C-2 lists the printer status file entries.COLUMNS="3"LBL="C-2"Table C-2 ID="94365" (continued) Printer Status File EntriesLEFT="0" WIDTH="113"Key FieldLEFT="120" WIDTH="113"Info Field Type LEFT="240" WIDTH="104"DefaultLEFT="0" WIDTH="113"Operational StatusLEFT="120" WIDTH="113"<keyword>LEFT="240" WIDTH="104"IdleLEFT="0" WIDTH="113"Media SizeLEFT="120" WIDTH="113"<keyword> [Land]LEFT="240" WIDTH="104"ALEFT="0" WIDTH="113"Media TypeLEFT="120" WIDTH="113"<keyword>LEFT="240" WIDTH="104"PaperLEFT="0" WIDTH="113"Number of ColorsLEFT="120" WIDTH="113"<dataentry>LEFT="240" WIDTH="104"1 k 1 chunkyLEFT="0" WIDTH="113"Printer OptionsLEFT="120" WIDTH="113"<string>LEFT="240" WIDTH="104"(empty string)LEFT="0" WIDTH="113"Validation MaskLEFT="120" WIDTH="113"<hbyte>LEFT="240" WIDTH="104"0LEFT="0" WIDTH="113"ErrorLEFT="120" WIDTH="113"<msgentry>LEFT="240" WIDTH="104"(no message)LEFT="0" WIDTH="113"WarningLEFT="120" WIDTH="113"<msgentry>LEFT="240" WIDTH="104"(no message)LEFT="0" WIDTH="113"InformationLEFT="120" WIDTH="113"<msgentry>LEFT="240" WIDTH="104"(no message)LBL="" HELPID=""Operational StatusID="apenC83"Operational StatusID="apenC84" is the keyword specifying the current operational status of the printer. The possible values are Idle, Busy, Faulted, and Unavailable.The status Faulted indicates that there is a problem with the printer but not with communication to the printer. The Unavailable designation is similar to the Faulted state but indicates that communication could not be established with the printer. The default value is Idle.LBL="" HELPID=""Media SizeID="apenC85"Media SizeID="apenC86" is the keyword indicating the currently loaded media size. The media size keywords are listed in the file pod.h. The keyword is the size name listed with the PD_SIZE_ prefix removed. The size names listed in pod.h with the suffix _LAND indicate landscape orientation and are specified in the entry by the keyword Land.LBL="" HELPID=""Media TypeID="apenC87"Media TypeID="apenC88" is the keyword indicating the currently loaded media type. The value is Paper, Transparency, Other, or Unknown. The default is Paper.LBL="" HELPID=""Number of ColorsID="apenC89"ID="apenC90"This field specifies not only the number of output colors but the colorspace, depth, and organization of the output data. There is one required field and three optional fields. For proper operation of printing filters, it is strongly recommended that the optional fields be specified.The Number of Colors<infofield> has the format <dataentry> defined as<int> [<keyword> <int> <keyword>]Arguments:<int>Required. Specifies the number of output colors the printer can currently print. If only this field is present, the following defaults applyCOLUMNS="4"LEFT="0" WIDTH="65"# of colorsLEFT="70" WIDTH="65"colorspaceLEFT="140" WIDTH="65"depthLEFT="210" WIDTH="65"organizationLEFT="0" WIDTH="65"1LEFT="70" WIDTH="65"kLEFT="140" WIDTH="65"1LEFT="210" WIDTH="65"chunkyLEFT="0" WIDTH="65"3LEFT="70" WIDTH="65"cmyLEFT="140" WIDTH="65"1LEFT="210" WIDTH="65"chunkyLEFT="0" WIDTH="65"4LEFT="70" WIDTH="65"cmykLEFT="140" WIDTH="65"1LEFT="210" WIDTH="65"chunky<keyword>Optional. This field specifies the output colorspace and is either k, rgb, cmy, ymc, cmyk, ymck, w, or kcmy.<int>Optional. This field specifies the number of bits per color component and may be 1, 4, or 8.<keyword>Optional. This field specifies the data organization of the output data and is either chunky or planar.An example output specification is3 rgb 4 planarThis specifies a three-color RGB output with four bits per component (12 bits total) and a planar data organization. Refer to the libstiff(3) reference page for additional information on raster data output formats.LBL="" HELPID=""Printer OptionsID="apenC91"ID="apenC92"This field is used to describe the currently available optional equipment or configurations. The field is also used to indicate the current printer resolution for printers that allow multiple output resolutions. To indicate the current resolution, the stringCurrentRes = <int> x <int>is specified. The first integer is the horizontal resolution in dots per inch, and the second integer is the vertical resolution in the same units. The current resolution values are used by printing filters such as the PostScript interpreter psrip to calculate margins for printers whose resolutions can change, and it is very important that printer drivers update this information field to ensure proper rendering.LBL="" HELPID=""Validation MaskID="apenC93"ID="apenC94"This field can be used to differentiate among media entries that have the same media name but differ in other respects (for example, resolution). The field is a bit mask and so, to fully differentiate among similar entries, the values must be powers of two. Refer to the PDReadStatus(3) reference page for more information on the use of this field.LBL="" HELPID=""Error, Warning, and Information OptionsID="apenC95"ID="apenC96"ID="apenC97"Each Error, Warning, and Information message ID="apenC98"ID="apenC99"ID="apenC100"<infofield> has the format <msgentry> defined as<hbyte> [<hbyte> [<hbyte>]] <separator> <string>These three entries indicate messages written by the printer driver to provide information to the printer user regarding the state of the printer. The three hex bytes provide a message code. The available message codes are listed in pod.h (see PD_ERROR_*). The low-order three bytes of the codes listed in pod.h are the codes specified in this field. The high-order byte of the code is implied by the first field (for example., Information = 00, Warning = 01, Error = 02). The last field is a string providing the text for the message. There can be up to PD_MESSAGE_MAX (see pod.h) message entries in a status file. An example of a complete message entry isInformation | 01 00 00 | version: driver = 00.00See the PDMakeMessage() routine for the best method of construction these messages. For the sake of internationalization, it is strongly recommended that you do not customize messages.LBL="" HELPID=""ID="62827"Printer Log File FormatID="apenC101"The log file is not currently implemented. You should supply an empty file in /usr/spool/lp/pod with the name <printer name>.log, and should not write to the log file.LBL="D"ID="34235"Transition NotesThis appendix explains how application and printer driver developers can take advantage of the new features in Impressario 2.0.The following major topics are discussed:IDREF="77181" TYPE="TITLE""Notes for Application Developers"IDREF="26272" TYPE="TITLE""Notes for Printer Driver Developers"IDREF="19204" TYPE="TITLE""General Changes in IRIX 6.2"LBL="" HELPID=""ID="77181"Notes for Application DevelopersChanges that application developers should be aware of arePrintPanel(1) only runs printer graphical options panels that are in the/var/spool/lp/gui_interface/ELF directory. Because IRIX 6.2 does not run COFF executables, graphical options panels in the COFF-related/var/spool/lp/gui_interface directory are ignored. This change can be seen in PrintOptionPanel.c in /usr/impressario/src/libprintui.libimp(3) now supports International Color Consortium (ICC) color profiles embedded in SGI image files. It is available as a MIPS2 32-bit, a MIPS3 N32 (high performance 32-bit), or a MIPS3 64-bit library.libprintui(3X) is available as a MIPS2 32-bit or MIPS3 N32 library.See the c_dev release notes for information about 32-bit, n32 and 64-bit compilations.LBL="" HELPID=""ID="26272"Notes for Printer Driver DevelopersLBL="" HELPID=""Changes to the PostScript Interpreter (psrip)NoteAdobe Systems, Inc. imposes strict limitations on the use of the Configurable PostScript Interpreter by developers. Please refer to IDREF="38738" TYPE="TITLE"Appendix H, "Using the Adobe Configurable PostScript Interpreter," for details.The PostScript interpreter, psrip, has been upgraded to an Adobe Level II Configurable PostScript Interpreter (CPSI).You can find the Adobe PostScript version number of psrip by using the command /usr/lib/print/psrip -x Two significant improvements are its ability to set the gamma correction for individual color channels, and its ability to invoke psrip as a band device as well as a frame device. (You can also let it choose between them.) A band device renders the output raster image as a series of sequential bands rather than as a complete entity. It thus usually requires much less memory than a frame device. (A minimum band size of 5 megabytes is recommended.) See the psrip(1) reference pages for all the new features.psrip is the only executable in Impressario 2.0 that is licensed. It uses a FLEXlm node-locked license, stored in the file /var/flexlm/license.dat, and returns an error if the license is not available. You can use the License Manager in the System toolchest menu to update software licenses. For more information on obtaining a license, see the file /usr/lib/print/data/psrip_expired_msg. Additional information on FLEXlm can be found in the online manuals FLEXlm End User Manual and FLEXlm Programming Guide.psrip always runs as set user ID lp to guarantee that its files have the same ownership.This is necessary because psrip creates temporary and permanent files in /var/spool/lp/psparams and needs to be able to modify them.Halftone screens are found in /usr/lib/print/data/screens. Three screens are available:Impr1_2_Default. This is the default screen used in Impresario 1.2. It provides a clustered-style threshold array.Impr2_0_Default. This is the Impressario 2.0 default screen. Because all default screen values are defined within /usr/lib/print/data/psrip/startup.ps or psrip, the file itself is currently empty. The file is here in case the default changes in the future.Impr2_0_Default_UA. Similar to the Impr2_0_Default screen, its colors (C,M,Y,(K)) are un-aligned: They are not placed directly on top of each other. This results in colors that are more saturated at the expense of having some grays and blacks with a purple cast. It is recommended for image files like TIFF and GIF.The psrip -I option can be used to select between these screens. See the model file /usr/impressario/src/models/laserjetPJL_model for examples.Fonts are in the directory/usr/lib/DPS. psrip uses the /usr/lib/DPS/AdobeFonts.upr file to determine the available fonts. The makepsres(1) function, which is automatically run (as an exitop) when the user quits the Software Manager after installing the dps_eoe.sw.dps sub-system, builds /usr/lib/DPS/AdobeFonts.upr based on the installed fonts.The directory /usr/lib/print/data/psrip contains other resources used by psrip including Color Rendering Dictionaries (CRDs) and the default startup.ps file.There are some other changes in psrip:The CHUNKY output formats oldk, oldcmy, and oldcmyk, provided for compatibility with previous releases of Impressario, have been removed.psrip now ignores the -T option.The psrip command-line option rotate is now limited to rotating an image in 90 degree increments.LBL="" HELPID=""Changes Affecting Model Files For Impressario 2.0, there is an updated sample model file for HP LaserJet printers, /usr/impressario/src/models/laserjetPJL_model. The Impressario 1.2 version of the laserjet_modellp model file is still available for comparison and is found in the directory /usr/impressario/src/models. There are several major changes in the updated file:Many of the printer drivers now write to standard output instead of directly to the parallel port. This allows the driver output to be piped to a device-specific driver such as phandler, which drives printers from the parallel port, or nethandler, which drives printers from network adapters such as the HP JetDirect network adapter. See the file /usr/impressario/src/models/laserjetPJL_model for examples.Although lptops is still available, there is a new ASCII-text-to-PostScript filter, text2ps.NoteAll Impressario model files now use text2ps to convert ASCII text files to PostScript and your model files should also.TipUnlike lptops, text2ps cannot print pages in reverse order. To reverse pages with text2ps, use the psselect filter. (The file type rules used by fileconvert have been updated to use psselect to do this.)Starting with IRIX 6.2, the man-t command now invokes /usr/lib/print/manprint which calls lp with the -o"-manpage" option if Impressario is installed. Impressario model files have been updated to support this. You should add similar support to your reference pages.As mentioned in the previous section, psrip uses a FLEXlm license. Model files should check for a valid license and disable the print spooler if one is not found. See the /usr/impressario/src/models/laserjetPJL_model file for an example.Other changes of interest in Impressario 2.0 are as follows:text2pcl has been updated to support A3 and B paper sizes.A bug that prevented the OPTION string in the model files from being parsed has been fixed. It is now possible for a string likeOPTIONS=numcolors=3 gamma=1.0 default_profile=hp500c06.pfto set the numcolors, gamma, and default_profile variables when the Printer Manager is used to install the model file into /var/spool/lp/interface.When using psrip, you can set the gamma value for each color channel. See the /var/spool/lp/model/deskjetII_model model file for an example.Finally, releases of IRIX after version 6.2 will not support CTR (Compiled Type Rule) database files. Your model files may be checking for this file using code like this:if [ ! -r /usr/lib/filetype/workspace.ctr ]; then
disable -r"WorkSpace filetype database not built. Type `su; cd /usr/lib/filetype; make'" \
$printer 1>>$logfile 2>&1
exit 2
fiYou should remove or comment out the above block of code. Future versions of fileconvert will map the old filename, workspace.ctr, to the new name, desktop.otr, to maintain backward compatibility. Even so, the file /usr/lib/filetype/workspace.ctr may not exist, so you should still remove the above code.LBL="" HELPID=""Changes Affecting POD Data FilesStarting with Impressario 2.0, a new logical AND operator, &, is available for font lists. Now the list of fonts on the printer can be logically AND'ed with the list of fonts on the print server, generating a list of common fonts that the graphical options panel can present to the user. The common list is important because the text2ps filter uses the font metric information of the print server fonts to determine where line breaks and page breaks should be made. The AND operator is intended for printer drivers that send PostScript directly to the printer. See IDREF="64689" TYPE="TITLE"Appendix C, "Printer Object Database (POD) File Formats,"IDREF="64689" TYPE="TEXT"IDREF="64689" TYPE="TEXT" for an example.LBL="" HELPID=""Changes Affecting Printer DriversSome changes that affect printer drivers areThe laserjet driver has been updated and renamed laserjetPJL. The source code is available in the /usr/impressario/src/drivers/laserjetPJL directory.Printer drivers that use the parallel port now check only the first eight characters of the output device, instead of looking for it to be /dev/plp. This allows them to support /dev/plp1, /dev/plp11, and so on. Developers should update their drivers to behave in a similar manner.Most printer drivers that directly controlled the parallel port now send output to standard output. The output is then piped to phandler or nethandler in the model file. NoteA general purpose driver for the serial port does not exist.phandler has been updated. The source code is available in the directory /usr/impressario/src/drivers/phandler.Another change may be necessary for drivers using nethandler. To avoid network printer timeouts, printer drivers that are meant to be used with nethandler should not send data to standard output until they read something from standard input. By waiting, the drivers can avoid initializing the printer prematurely because nethandler won't open a socket connection to the printer until it receives data from the driver via standard input.Here is the underlying problem. When the printer driver is invoked from a model file,image2ps image_file | psrip | printer_driver | nethandlera delay is introduced as the programs upstream from the printer driver process the data. If the image being processed is complex, the printer driver may not see data on standard input for some time. If the printer driver sends initialization commands to the printer immediately, nethandler will open a socket connection to the printer to deliver them. Most network printers then start a timeout sequence and close the socket if they do not see any more data before the timeout expires (typically 90 seconds to 2 minutes). If the processing upstream from the printer driver takes longer than the timeout period, the socket connection will be closed by the printer and nethandler will return an error. Recovery from this is difficult because trying again will probably have the same result.Current printer drivers probably perform this sequence of events (which risks a timeout):parse command line
send commands to printer to initialize it
while (data to read from standard input) do
read data from input
process data and format for printer
output data to printer
done
cleanupThe timeout problem can be addressed by modifying the printer drivers so:parse command line
while (data to read from standard input) do
read data from input
process data and format for printer
(if never initialized) send commands to printer to initialize it
output data to printer
done
cleanupLBL="" HELPID=""Changes to the Graphical Options PanelTipWhen a print client is configured, it copies the Graphical Printer Options Panel executable from the print server to /var/spool/lp/gui_interface/ELF. By default, IRIX 6.2 generates o32 MIPS2 ELF binaries. MIPS2 executables will not run on IRIX 5.3 systems with a MIPS R3000 processor, the configuration of many Indigo workstations. (IRIX 6.2 is not supported on R3000 systems.) Compile the Graphical Printer Options Panel under IRIX 5.3 if you wish to support IRIX 5.3 systems running on a R3000. The subsystem impr_dev.sw5_3 contains all of the Impressario 2.0 libraries compiled under IRIX 5.3. The libraries are installed in /usr/impressario/53libs and can be copied to your 5.3 development system.All of the Graphical Printer Options Panel executables supplied in Impressario 2.0 were compiled and linked under IRIX 5.3.The Graphical Printer Options Panel now has a context-sensitive help panel at the top of the window. This gives a short description of any option pointed to with the mouse. See the sample source code in /usr/impressario/src/gui_models/laserjetPJL.LBL="" HELPID=""ID="19204"General Changes in IRIX 6.2Because IRIX 6.2 does not support COFF executables (IRIX 6.2 compilers cannot even generate COFF executables) developers need to ship ELF executables. They need to ship COFF executables only if they wish to support IRIX 4.0.5 systems. IRIX 6.2 includes the utility /usr/sbin/coffcheck, which warns users about the presence of COFF executables. coffcheck ignores a COFF executable in the /var/spool/lp/gui_model or /var/spool/lp/gui_interface directory if there is an ELF executable of the same name in /var/spool/lp/gui_model/ELF or /var/spool/lp/gui_interface/ELF, respectively. This arrangement allows a 6.2 print server to support a 4.0.5 print client, because a 4.0.5 client will request the COFF version of the Graphical Printer Options file.Other features that are new with IRIX 6.2 are listed below:The fonts found in the Impressario 1.2 subsystem impr_fonts.sw.adobe22 are bundled with the base operating system. They have been removed from Impressario.The Printer Manager now lists SCSI devices that identify themselves as CPUs, such as certain dye-sublimation printers.When a printer is being added, the Add Printers menu of the Printer Manager displays a connection type, such as SCSI, only if there is a driver installed that supports that connection type.LBL="E"ID="36071"Scanner Driver ArchitectureID="apenE1"This appendix discusses scanner driver architecture. It provides a detailed analysis and discussion of the template scanner driver.The following major topics are discussed:IDREF="51154" TYPE="TITLE""Overview"IDREF="61147" TYPE="TITLE""Driver Structure"IDREF="17204" TYPE="TITLE""Type Conversion Macros"IDREF="29153" TYPE="TITLE""Scanner Functions"IDREF="36015" TYPE="TITLE""Queues and Multi-Threaded Scanner Drivers"LBL="" HELPID=""ID="51154"OverviewScanner drivers are programs that are executed by applications that link with ID="apenE2"libscan.a and call ID="apenE3"SCOpen(3). They accept commands from the application via an input pipe and return results via an output pipe.All scanner drivers must implement the basic set of commands so that any application using the libscan interface can have access to the functionality offered by the scanner. Many library routines are provided for scanner driver developers to implement functionality in software that may not be implemented in hardware for some scanners. The support routines for writing scanner drivers can be found in libscan.a.LBL="" HELPID=""ID="61147"Driver StructureID="apenE4"A scanner driver consists of a number of functions that implement the set of commands required to drive the scanner. In the main routine, a table of these functions, with the position of each function in the table corresponding to its SCN #define in scanipc.h, is passed to SCDriverSetCallbacks(), then SCDriverMainLoop() is called.SCDriverMainLoop() waits for input from the application and calls the function in the table corresponding to each command received. Each function has the following prototype:void scanfunc(int cmd, SCARG *arg, SCRES *res);Arguments:cmdContains the SCN #define of the command to be executed.argIs the argument to this scanning function. SCARG is defined in scandrv.h as follows:typedef struct tag_scarg {
void *data;
int len;
} SCARG;arg->data points to the arguments transferred from the application; the meaning of arg->data depends upon the cmd (see below).arg->len encodes the byte length of arg->data.resIs the result of this scanning function. SCRES is defined in scandrv.h as follows:typedef struct tag_scres {
void *data;
int len;
void *freeparam;
void (*free)(void *param, void *data);
int errno;
char *errmsg;
} SCRES;res->data should be set to point to the data to be returned to the application as a result of cmd.res->len is the byte length of res->data.res->free is a pointer to a function that is called if it is nonzero after res->data has been transferred to the application. The function is called with res->freeparam as its first argument and res->data as its second argument.res->errno should be set to one of the SCE #defines in /usr/include/scanner.h or one of the errno values from /usr/include/sys/errno.h if an error occurs during the execution of cmd. If res->errno is nonzero, the libscan function being executed on the application side returns an error status, and SCerrno is set to the value of res->errno.res->errmsg is the error message pointer. If res->errno is set to SCEDRVMSG, then res->errmsg should point to a driver-specific error message.Before a scanning function is called, the entire res structure is zeroed. Scanning functions are allowed to assume that any member of the res structure not explicitly set remains set to 0.LBL="" HELPID=""ID="29153"Scanner FunctionsID="apenE5"LBL="" HELPID=""Required Scanner FunctionsID="apenE6"ID="apenE7"All scanner drivers must implement the functions listed in IDREF="18671" TYPE="TABLE"Table E-1.COLUMNS="2"LBL="E-1"Table E-1 ID="18671" (continued) Scanner Driver FunctionsLEFT="0" WIDTH="117"FunctionLEFT="125" WIDTH="263"DescriptionLEFT="0" WIDTH="117"SCN_INITOK()LEFT="125" WIDTH="263"Checks for successful scanner driver initializationLEFT="0" WIDTH="117"SCN_PAGESIZE()LEFT="125" WIDTH="263"Returns the size of the scan area that is supported by the scannerLEFT="0" WIDTH="117"SCN_MINMAXRES()LEFT="125" WIDTH="263"Returns the smallest and largest horizontal and vertical resolutionLEFT="0" WIDTH="117"SCN_NRES()LEFT="125" WIDTH="263"Returns the number of resolution pairs supported in hardwareLEFT="0" WIDTH="117"SCN_RES()LEFT="125" WIDTH="263"Returns floating-point numbers representing the supported
hardware resolutionsLEFT="0" WIDTH="117"SCN_NTYPES()LEFT="125" WIDTH="263"Returns the number of data types supported by the driverLEFT="0" WIDTH="117"SCN_TYPES()LEFT="125" WIDTH="263"Returns an array of SCDATATYPE objects, one for each of the
types supported by the driverLEFT="0" WIDTH="117"SCN_FEEDERGETFLAGS()LEFT="125" WIDTH="263"Gets the document feeder flagsLEFT="0" WIDTH="117"SCN_FEEDERSETFLAGS()LEFT="125" WIDTH="263"Sets the document feeder flagsLEFT="0" WIDTH="117"SCN_FEEDERREADY()LEFT="125" WIDTH="263"Determines if the feeder is ready to be advancedLEFT="0" WIDTH="117"SCN_FEEDERADVANCE()LEFT="125" WIDTH="263"Advances the feeder to the next documentLEFT="0" WIDTH="117"SCN_SETUP()LEFT="125" WIDTH="263"Sets the scanning parametersLEFT="0" WIDTH="117"SCN_GETSIZE()LEFT="125" WIDTH="263"Returns scan line width (in bytes and pixels) and the number of
scan linesLEFT="0" WIDTH="117"SCN_SCAN()LEFT="125" WIDTH="263"Tells the scanner driver to start scanningLEFT="0" WIDTH="117"SCN_ABORT()LEFT="125" WIDTH="263"Stops the scan and releases temporarily allocated resourcesLEFT="0" WIDTH="117"SCN_DIE()LEFT="125" WIDTH="263"Cleans up and calls exit()LBL="" HELPID=""SCN_INITOK() FunctionID="apenE8"ID="apenE9"ID="apenE10"arg->data: NULL
res->data: NULLThis function exists as a mechanism for the application to determine whether the scanner driver managed to initialize itself and the scanner properly. If any problem occurred during initialization, res->errno should be set to one of the SCE #defines in scanner.h; otherwise, no action is necessary.LBL="" HELPID=""SCN_PAGESIZE() FunctionID="apenE11"ID="apenE12"ID="apenE13"arg->data: int * (Metric)
res->data: SCWINDOW *
typedef struct tag_scwindow {
float x, y, width, height;
} SCWINDOW;This function returns the size of the scannable area supported by the scanner. Fill res->data in with the x, y, width, and height of the scannable area in inches or centimeters, depending on whether arg->data is SC_INCHES or SC_CENTIM.LBL="" HELPID=""SCN_MINMAXRES() FunctionID="apenE14"ID="apenE15"ID="apenE16"arg->data: NULL
res->data: SCMINMAXRES *
typedef struct tag_scminmaxres {
float minx, miny, maxx, maxy;
} SCMINMAXRES;This function sets the smallest and largest horizontal and vertical resolutions. res->data->minx should be set to the smallest horizontal resolution supported in hardware by the scanner, res->data->miny to the smallest vertical resolution, res->data->maxx to the largest horizontal resolution, and res->data->maxy to the largest vertical resolution.LBL="" HELPID=""SCN_NRES() FunctionID="apenE17"ID="apenE18"ID="apenE19"arg->data: NULL
res->data: int *This function sets the number of resolution pairs supported in hardware. *res->data should be set to the number of (xres, yres) resolution pairs supported in hardware by the scanner.LBL="" HELPID=""SCN_RES() FunctionID="apenE20"ID="apenE21"ID="apenE22"arg->data: int *
res->data: float *This function sets floating-point numbers representing supported hardware resolutions. arg->data points to the metric of the resolution; either SC_INCHES for pixels/inch or SC_CENTIM for pixels/centimeter. res->data should be set to point to a floating-point array that represent supported hardware resolutions. There should be an even number of resolutions, with all of the horizontal resolutions first, then all of the vertical resolutions.NoteAll scanner drivers must support arbitrary resolutions; software routines are provided to perform zoom operations. The above information is provided so that scanner application developers can retrieve pure data from the scanner and perform their own zooming (with filters; libscan zooming does no filtering) to achieve the desired resolution.LBL="" HELPID=""SCN_NTYPES() FunctionID="apenE23"ID="apenE24"ID="apenE25"arg->data: NULL
res->data: int *This function sets the number of data types supported by the driver. *res->data should be set to the number of data types supported by this scanner driver.LBL="" HELPID=""SCN_TYPES() FunctionID="apenE26"ID="apenE27"ID="apenE28"arg->data: NULL
res->data: SCDATATYPE *
typedef struct tag_scdatatype {
unsigned int packing : 4;
unsigned int channels : 4;
unsigned int type : 8;
unsigned int bpp : 8;
} SCDATATYPE;The res->data of the SCN_TYPES() function points to an array of SCDATATYPE objects, one for each of the types supported by the scanner driver.All scanner drivers must support monochrome data; that is, the type { SC_PACKPIX, 1, SC_MONO, 1 }. All scanner drivers that support any kind of greyscale or color output must support the type { SC_PACKPIX, 1, SC_GREY, 8 }; that is, 8-bit gray-scale. All scanner drivers that support any kind of color output must support either { SC_PACKPIX, 3, SC_RGB, 8 } (24-bit CHUNKY color data) or { SC_PACKPLANE, 3, SC_RGB, 8 } (24-bit planar color data).Library routines in libscan.a exist to facilitate compliance with these conventions.LBL="" HELPID=""SCN_FEEDERGETFLAGS() FunctionID="apenE29"ID="apenE30"ID="apenE31"arg->data: NULL
res->data: SCFEEDERFLAGS *
typedef unsigned int SCFEEDERFLAGS;This function returns the feeder flags for this scanner to the application. See IDREF="28616" TYPE="TITLE""Header Files" in Chapter 7.LBL="" HELPID=""SCN_FEEDERSETFLAGS() FunctionID="apenE32"ID="apenE33"ID="apenE34"arg->data: SCFEEDERFLAGS *
res->data: NULLThis function sets the feeder flags.LBL="" HELPID=""SCN_FEEDERREADY() FunctionID="apenE35"ID="apenE36"ID="apenE37"arg->data: NULL
res->data: NULLThis function determines whether or not the feeder is ready for an advance command.LBL="" HELPID=""SCN_FEEDERADVANCE() FunctionID="apenE38"ID="apenE39"ID="apenE40"arg->data: NULL
res->data: NULLThis function causes the feeder to advance to the next document.LBL="" HELPID=""SCN_SETUP() FunctionID="apenE41"ID="apenE42"ID="apenE43"arg->data: SCSETUP *
res->data: NULL
typedef struct tag_scsetup {
int preview;
SCDATATYPE type;
int rmetric;
float xres, yres;
int wmetric;
float x, y, width, height;
} SCSETUP;The SCN_SETUP() function sets the scanning parameters. The upper-left x and y coordinates, the width, and the height are specified in either pixels, inches, or centimeters, depending on whether arg->data->wmetric is SC_PIXELS, SC_INCHES, or SC_CENTIM.Set the scanning horizontal and vertical resolutions, in pixels per inch or pixels per centimeter, depending on the value of arg->data->rmetric. Set the data type for scanning. If this is a preview, arg->data->preview will have a nonzero value.NoteIf a resolution or combination of resolutions not supported in hardware is specified, the driver MUST zoom the image in order to supply the requested resolution. Library routines to aid zooming are available in libscan.a.LBL="" HELPID=""SCN_GETSIZE() FunctionID="apenE44"ID="apenE45"ID="apenE46"arg->data: NULL
res->data: SCSIZE *
typedef struct tag_scsize {
long xbytes, xpixels, ysize;
} SCSIZE;This function returns, to the scanning application, the width of a scan line in bytes and pixels, and the number of scan lines in the scan. This is called after SCN_SETUP() so the application knows exactly how much data to expect.LBL="" HELPID=""SCN_SCAN() FunctionID="apenE47"ID="apenE48"ID="apenE49"arg->data: NULLres->data: NULLThis function tells the scanner driver to initiate scanning.LBL="" HELPID=""SCN_ABORT() FunctionID="apenE50"ID="apenE51"ID="apenE52"arg->data: NULL
res->data: NULLThis function stops the scan and releases any resources temporarily allocated. The application has decided to stop retrieving data before scanning has been completed. The driver should physically stop the scan and release any resources that were temporarily allocated for the scan.LBL="" HELPID=""SCN_DIE() FunctionID="apenE53"ID="apenE54"ID="apenE55"arg->data: NULL
res->data: NULLThis function cleans up and calls exit(2). The application has demanded that the driver terminate. This function should not return; it should perform any necessary cleanup and then call exit.LBL="" HELPID=""ID="17204"Type Conversion MacrosThe macros listed in IDREF="40754" TYPE="TABLE"Table E-2 are provided to convert between data types.COLUMNS="2"LBL="E-2"Table E-2 ID="40754"Type Conversion MacrosLEFT="0" WIDTH="81"MacroLEFT="90" WIDTH="252"DescriptionLEFT="0" WIDTH="81"GRIDTOFLOATLEFT="90" WIDTH="252"Convert from grid format to floating-point formatLEFT="0" WIDTH="81"FLOATTOGRIDLEFT="90" WIDTH="252"Convert from floating-point format to grid format LBL="" HELPID=""GRIDTOFLOAT and FLOATTOGRID MacrosGRIDTOFLOAT(int pos, int n)FLOATTOGRID(float pos, int n)These macros determine which destination pixel or line the source pixel or line at pos corresponds to. For example, if we are scanning at 120 dpi, but the application has requested 100 dpi, and our scan height is 1 inch, we need to skip 20 scan lines to provide the desired resolution. The following loop obtains scan lines from the scanner and passes them on to the application:float fy;
int imgy, scany;
while (imgy < 100) {
fy = GRIDTOFLOAT(imgy, 100);
scany = FLOATTOGRID(fy, 120);
...
/* Get the scany'th scan line from the scanner */
/* Do conversion and horizontal zooming */
/* Call SCDriverPutRow */
imgy++;
}LBL="" HELPID=""Zooming and Type Conversion FunctionsID="apenE56"The functions listed in IDREF="57245" TYPE="TABLE"Table E-3 are provided to support zooming and converting between data types.All conversion routines simultaneously zoom, so that only one conversion per line should ever be necessary.COLUMNS="2"LBL="E-3"Table E-3 ID="57245" (continued) Zooming and Type Conversion FunctionsID="apenE57"LEFT="0" WIDTH="118"FunctionLEFT="125" WIDTH="216"DescriptionLEFT="0" WIDTH="118"SCCreateZoomMap()LEFT="125" WIDTH="216"Creates a zoom mapLEFT="0" WIDTH="118"SCDestroyZoomMap()LEFT="125" WIDTH="216"Frees memory allocated to store a zoom mapLEFT="0" WIDTH="118"SCZoomRow1()LEFT="125" WIDTH="216"Zooms a row of 1-bit pixelsLEFT="0" WIDTH="118"SCZoomRow8()LEFT="125" WIDTH="216"Zooms a row of 8-bit pixelsLEFT="0" WIDTH="118"SCZoomRow24()LEFT="125" WIDTH="216"Zooms a row of 24-bit pixelsLEFT="0" WIDTH="118"SCZoomRow32()LEFT="125" WIDTH="216"Zooms a row of 32-bit pixelsLEFT="0" WIDTH="118"SCBandRGB8ToPixelRGB8()LEFT="125" WIDTH="216"Converts a row of pixels, in three rows (R, G, and B)
of 8-bit components per pixel, to a row of 24-bit pixelsLEFT="0" WIDTH="118"SCGrey8ToMono()LEFT="125" WIDTH="216"Converts a row of pixels from 8-bit greyscale to
monochromeLBL="" HELPID=""SCCreateZoomMap() FunctionID="apenE58"ID="apenE59"ID="apenE60"int *SCCreateZoomMap(int anx, int bnx);This function creates a zoom map. When zooming in the horizontal direction, it is wasteful to use GRIDTOFLOAT and FLOATTOGRID for every pixel of every line, since the same calculations would be repeated many times. A zoom map is an array of bnx integers, each of which is the pixel between 0 and anx - 1 that should be used when zooming a row of anx pixels to a row of bnx pixels. The zooming and conversion functions all take zoom maps for efficient zooming; for conversion functions where no zooming is to occur, the zmap parameter can be NULL.LBL="" HELPID=""SCDestroyZoomMap() FunctionID="apenE61"ID="apenE62"ID="apenE63"void SCDestroyZoomMap(int *zmap);This function frees memory allocated to store a zoom map.LBL="" HELPID=""SCZoomRow1() FunctionID="apenE64"ID="apenE65"ID="apenE66"void SCZoomRow1(char *abuf, int anx, char *bbuf, int bnx, int *zmap);This function zooms a row of anx pixels to a row of bnx pixels, 1 bit per pixel.LBL="" HELPID=""SCZoomRow8() FunctionID="apenE67"ID="apenE68"ID="apenE69"void SCZoomRow8(char *abuf, int anx, char *bbuf, int bnx, int *zmap);This function zooms a row of anx pixels to a row of bnx pixels, 8 bits per pixel.LBL="" HELPID=""SCZoomRow24() FunctionID="apenE70"ID="apenE71"ID="apenE72"void SCZoomRow24(void *abuf, int anx, void *bbuf, int bnx, int *zmap);This function zooms a row of anx pixels to a row of bnx pixels, 24 bits per pixel.LBL="" HELPID=""SCZoomRow32() FunctionID="apenE73"ID="apenE74"ID="apenE75"void SCZoomRow32(void *abuf, int anx, void *bbuf, int bnx, int *zmap);This function zooms a row of anx pixels to a row of bnx pixels, 32 bits per pixel.LBL="" HELPID=""SCBandRGB8ToPixelRGB8() FunctionID="apenE76"ID="apenE77"ID="apenE78"void SCBandRGB8ToPixelRGB8(void *frombuf, int fromx, void *tobuf, int tox, int *zmap);This function converts a row of fromx pixels, laid out in three rows (R, G, and B) of 8-bit components per pixel, to a row of tox pixels, 24 bits per pixel.LBL="" HELPID=""SCGrey8ToMono() FunctionID="apenE79"ID="apenE80"ID="apenE81"void SCGrey8ToMono(unsigned char thresh, void *frombuf, int fromx, void *tobuf, int tox, int *zmap);This function converts a row of pixels from 8-bit greyscale to monochrome, thresholding each pixel with thresh.LBL="" HELPID=""ID="36015"Queues and Multi-Threaded Scanner DriversID="apenE82"To achieve optimal performance in a scanner driver, it is helpful to parallelize the operations being performed. A pipeline carries data from the scanner to the ultimate destination, often a file. One can imagine that at the beginning of the pipeline, most of the time is spent waiting for I/O to complete. An intermediate image processing stage is CPU-bound as it zooms and converts rows of data. The final stage, writing to a file, is again I/O-bound.Rather than adding these times together, we notice that all three stages of the pipeline can occur at the same time; that is, while the scanning stage is waiting for I/O, the file-writing stage can also be waiting for I/O, and the image-processing stage can be using the CPU. As you can imagine, performance gets even better on multiprocessor systems.To support this, a multi-threaded queue interface is included in libscan.a. Each queue is semaphored so that the read thread can be different from the write thread, and so that the dequeue operation on an empty queue blocks until another thread has enqueued something.In the driver template, separate threads implement the scanning stage and the image-processing stage. The main thread of the driver simply starts the two processes and waits for more commands from the application.The driver template uses two queues: one to hold free buffers and one to hold freshly scanned lines. The amount of concurrency is metered by the initial size of the free queue; the scanning thread blocks when there are no more free buffers if it gets too far ahead of the image-processing thread.The scanning thread dequeues a buffer from the scan free queue, gets data from the scanner, and stores it in the buffer. Then it breaks the buffer up into scan lines, enqueueing each line on the scan queue (it is typically faster to scan chunks of lines rather than one line at a time).The image-processing thread dequeues a buffer from the scan queue. It then zooms and converts it, and writes the result to a stream that the application is reading to obtain the data. It puts the original buffer back on the scan free queue (actually, since the scanning thread breaks its buffer up into scan line-sized chunks, the image-processing thread has to know how to put the chunks back together).IDREF="56651" TYPE="GRAPHIC"Figure E-1 illustrates the scanning process.FILE="apenE-1.gif" POSITION="INLINE" SCALE="FALSE"LBL="E-1"Figure E-1 ID="56651"Scanner Driver ArchitectureID="apenE83"LBL="" HELPID=""Queue Manipulating FunctionsThe following functions are provided for manipulating queues:typedef struct tag_scqueue SCQUEUE;IDREF="75482" TYPE="TABLE"Table E-4 lists the queue manipulating functions.COLUMNS="2"LBL="E-4"Table E-4 ID="75482"Queue Manipulating FunctionsID="apenE84"LEFT="0" WIDTH="81"FunctionLEFT="90" WIDTH="268"DescriptionLEFT="0" WIDTH="81"SCCreateQueue()ID="apenE85"ID="apenE86"LEFT="90" WIDTH="268"Creates a queue that is multi-threaded safe and blocks on an empty
dequeueLEFT="0" WIDTH="81"SCDestroyQueue()ID="apenE87"ID="apenE88"LEFT="90" WIDTH="268"Frees the resources used by a queueLEFT="0" WIDTH="81"SCEnqueue()ID="apenE89"ID="apenE90"LEFT="90" WIDTH="268"Adds an element to the tail of the queueLEFT="0" WIDTH="81"SCDequeue()ID="apenE91"ID="apenE92"LEFT="90" WIDTH="268"Removes an element from the head of a queue and returns itLEFT="0" WIDTH="81"SCQueueSetExit()ID="apenE93"ID="apenE94"LEFT="90" WIDTH="268"Sets a flag associated with a queue that tells all queue users to exitLBL="" HELPID=""SCCreateQueue() FunctionID="apenE95"ID="apenE96"ID="apenE97"SCQUEUE * SCCreateQueue(int nelems);This function creates a queue that is multi-threaded safe and blocks on an empty dequeue. nelems is the maximum number of elements that can be stored in the newly created queue. Enqueue operations on full queues block until another thread has completed a dequeue operation.LBL="" HELPID=""SCDestroyQueue() FunctionID="apenE98"ID="apenE99"ID="apenE100"int SCDestroyQueue(SCQUEUE *q);This function frees the resources used by a queue.LBL="" HELPID=""SCEnqueue() FunctionID="apenE101"ID="apenE102"ID="apenE103"void SCEnqueue(SCQUEUE *q, void *data);This function adds an element to the tail of the queue. It unblocks a thread waiting to dequeue or blocks it if the queue is full.LBL="" HELPID=""SCDequeue() FunctionID="apenE104"ID="apenE105"ID="apenE106"void * SCDequeue(SCQUEUE *q);This function removes an element from the head of a queue and returns it. SCDequeue() unblocks a thread waiting to enqueue or blocks it if the queue is empty.LBL="" HELPID=""SCQueueSetExit() FunctionID="apenE107"ID="apenE108"ID="apenE109"void * SCQueueSetExit(SCQUEUE *q);This function sets a flag associated with a queue that tells all users of the queue to exit. Any thread blocking in SCEnqueue() or SCDequeue() is terminated. SCQueueSetExit() is used by the main thread of a scanner driver to tell the child threads to exit when the user aborts a scan.LBL="F"ID="14153"Reference PagesThis appendix lists all reference pages associated with Impressario. IDREF="78315" TYPE="TABLE"Table F-1 lists the general interest reference pages.COLUMNS="2"LBL="F-1"Table F-1 ID="78315"General Interest Reference PagesID="apenF1"LEFT="0" WIDTH="126"NamesLEFT="135" WIDTH="211"DescriptionLEFT="0" WIDTH="126"Impressario(1)ID="apenF2"ID="apenF3"LEFT="135" WIDTH="211"Printing and scanning environment for Silicon
Graphics systemsLEFT="0" WIDTH="126"glp(1), PrintPanel, printpanelID="apenF4"ID="apenF5"ID="apenF6"ID="apenF7"ID="apenF8"ID="apenF9"LEFT="135" WIDTH="211"Graphical lp printing commandLEFT="0" WIDTH="126"PrintStatus(1), printstatusID="apenF10"ID="apenF11"ID="apenF12"ID="apenF13"LEFT="135" WIDTH="211"Graphical printer status toolLEFT="0" WIDTH="126"gscan(1)ID="apenF14"ID="apenF15"LEFT="135" WIDTH="211"Graphical scanning toolLEFT="0" WIDTH="126"scanners(1M)ID="apenF16"ID="apenF17"LEFT="135" WIDTH="211"Scanner installation and management toolLEFT="0" WIDTH="126"fileconvert(1)ID="apenF18"ID="apenF19"LEFT="135" WIDTH="211"File to printer or filetype converterLEFT="0" WIDTH="126"vstiff(1)ID="apenF20"ID="apenF21"LEFT="135" WIDTH="211"Stream TIFF viewerLEFT="0" WIDTH="126"psrip(1)ID="apenF22"ID="apenF23"LEFT="135" WIDTH="211"PostScript file to raster data format converterLEFT="0" WIDTH="126"installfoliofonts(1)ID="apenF24"ID="apenF25"LEFT="135" WIDTH="211"PostScript font installation program for Adobe
Macintosh« Font Folioname='trade' font=symbol charset=fontspecific code=228
descr='[trade]' CDROMLEFT="0" WIDTH="126"installpcfonts(1)ID="apenF26"ID="apenF27"LEFT="135" WIDTH="211"PostScript font installation program for Adobe
descr='[trade]' PC floppy disksLEFT="0" WIDTH="126"printers(1M) ID="apenF28"ID="apenF29"LEFT="135" WIDTH="211"Printer installation and management programLEFT="0" WIDTH="126"print(1)LEFT="135" WIDTH="211"Printing subsystem, built on System V Release 3
printer spooling system, that uses ImpressarioIDREF="45816" TYPE="TABLE"Table F-2 lists the printing developers reference pages and IDREF="35045" TYPE="TABLE"Table F-3 lists the scanning developers reference pages. The software these reference pages describe utilizes the C application program interface (API).COLUMNS="2"LBL="F-2"Table F-2 ID="45816"Printing Developers Reference PagesID="apenF30"LEFT="0" WIDTH="63"NameLEFT="70" WIDTH="294"DescriptionLEFT="0" WIDTH="63"libspool(3)ID="apenF31"ID="apenF32"LEFT="70" WIDTH="294"An API to the UNIX printer spooling systems.LEFT="0" WIDTH="63"libpod(3)ID="apenF33"ID="apenF34"LEFT="70" WIDTH="294"An API to the printer object database (POD).LEFT="0" WIDTH="63"libprintui(3X)ID="apenF35"ID="apenF36"LEFT="70" WIDTH="294"An API to the PrintBox widget.LEFT="0" WIDTH="63"libstiff(3)ID="apenF37"ID="apenF38"LEFT="70" WIDTH="294"An API for reading and writing the STIFF (Stream TIFF) data file format.It
is described in detail in IDREF="68392" TYPE="TITLE"Appendix A.LEFT="0" WIDTH="63"libimp(3)ID="apenF39"ID="apenF40"LEFT="70" WIDTH="294"An API for reading and writing Silicon Graphics Image format files. It is
described in detail in IDREF="79172" TYPE="TITLE"Appendix B.COLUMNS="2"LBL="F-3"Table F-3 ID="35045"Scanning Developers Reference PagesID="apenF41"LEFT="0" WIDTH="63"NameLEFT="70" WIDTH="294"DescriptionLEFT="0" WIDTH="63"libscan(3)ID="apenF42"ID="apenF43"LEFT="70" WIDTH="294"An API for scanning.LEFT="0" WIDTH="63"libstiff(3)ID="apenF44"ID="apenF45"LEFT="70" WIDTH="294"An API for reading and writing the STIFF (Stream TIFF) data file format.It
is described in detail in IDREF="68392" TYPE="TITLE"Appendix A.LEFT="0" WIDTH="63"libimp(3)ID="apenF46"ID="apenF47"LEFT="70" WIDTH="294"An API for reading and writing Silicon Graphics image format files. It is
described in detail in IDREF="79172" TYPE="TITLE"Appendix B.LBL="G"ID="67009"Color Management In ImpressarioImpressario uses International Color Consortium (ICC) color profiles and PostScript Color Rendering Dictionaries (CRDs) for color management. This appendix discusses the following topics:IDREF="39552" TYPE="TITLE""An Overview"IDREF="29641" TYPE="TITLE""ICC Color Profiles"IDREF="24547" TYPE="TITLE""Color Rendering Dictionaries"IDREF="25614" TYPE="TITLE""Generating CRDs and ICC Profiles"LBL="" HELPID=""ID="39552"An OverviewColor management is the process of specifying the color characteristics of peripheral devices and applying this information to allow color to be used more consistently throughout the system. Different devices have different color characteristics. The characteristics can be physical differences such as paper and ink for printers and phosphors for monitors. They also can be color space differences. A color space is a conceptual model for representing color.Scanners and monitors usually use the RGB color space. Red, green, and blue are the primary colors in this space; all colors are mixtures of these. RGB is an additive color space. Red, green, and blue light are added to form a desired color. When full intensities of red, green, and blue light are used, the result is white light.Printers use the CMY or CMYK color space. Cyan, magenta, and yellow are the primary colors. It is a subtractive color space: the color is that of the light that is reflected after parts of the white-light spectrum are absorbed by the medium, such as ink on paper. Theoretically, a mixture of cyan, magenta, and yellow subtractive colorings results in black because all of the white light is absorbed. In reality, a black color, denoted by K, is usually used because the CMY ink-on-paper mixture does not absorb light perfectly.The technique of color management is to use color spaces to characterize input and output devices, and to provide the conversions needed to maintain consistent color use among them. Conversions may go directly from one color space to another, such as from RGB for a scanner to CMYK for a printer. Alternatively, conversions may make use of intermediary color spaces, such as CIE-based ones. (CIE stands for the Commission Internationale d'Eclairage.) The CIE color spaces are intended as representations of color as seen by the human eye. They are considered device-independent, in contrast to the RGB and CMYK spaces, whose color representations vary with the physical characteristics of the devices producing them. A common CIE-based space is CIELAB, which is based on the three types of stimuli to which the eye's retina responds. For a further discussion of color conversion, consult a text such as Computer Graphics: Principles and Practice, Second Edition, by Foley, van Dam, Feiner, and Hughes.Impressario provides two tools for color management: ICC color profiles for SGI, TIFF, GIF, JPEG, PCD, and PPM raster image filesPostScript CRDs for PostScript files that specify CIELAB-based color spacesLBL="" HELPID=""ID="29641"ICC Color ProfilesInternational Color Consortium(ICC) color profiles describe the color characteristics of source devices, such as scanners, and destination devices, such as printers. (A monitor is considered to be another type of device because it can be both a source and a destination.) Profiles are available for various scanners, printers, and monitors. By using the information from the source and destination profiles, a color correction can be determined and applied to the image.The scanning program gscan adds the ICC source profile to its output (a TIFF or Silicon Graphics image raster file). Embedding the source profile in the output allows the file to be moved to systems that don't have that profile. With gscan, the user can choose from several scanner profiles, or even turn off color management altogether. The IDREF="61221" BOOK="Impr_UG" FILE="" HDG="61221" INFO=""Impressario User's Guide
has further information on scanning and gscanDuring printing, color correction is applied to a raster image by the cocostiff or cocogif utility before the image is processed by the PostScript interpreter. (cocostiff (Color Correct Stream Tiff) and cocogif (Color Correct GIF) are part of the cms_eoe subsystem) The Impressario file convert rules automatically invoke cocostiff or cocogif.Use fileconvert to see how the file convert rules are applied:/usr/sbin/fileconvert -d ImpressarioRasterBitmap /usr/impressario/tests/data/testfile.sgireturnsPRINTFILES="/usr/impressario/tests/data/testfile.sgi" ; /usr/lib/print/sgi2stiff $IMPR_IMG2STIFFOPTS $PRINTFILES | /usr/sbin/cocostiff $IMPR_CMGTOPTS | /usr/lib/print/stiff2ps $IMPR_SGI2PSOPTS | /usr/lib/print/psrip $IMPR_PSRIPOPTSIn this example, sgi2stiff converts the SGI format to the STIFF format, the output being piped to cocostiff. The command-line options of cocostiff, -d hp650e06.pf for example, are contained in the environment variable $IMPR_CMGTOPTS. This value, like those of the other uppercase environment variables, is normally set in a printer model file. (See the cocostiff(1) reference page for details about specific command-line options.) cocostiff applies the color correction, and its output is piped to stiff2ps and then to psrip, the PostScript interpreter.It is important to note that an ICC profile describing the source device is needed to do color correction. As mentioned above, gscan embeds a source profile in the files it creates. Of course, not all files are created by gscan. If a source profile is not embedded in the raster file, cocostiff and cocogif use the ICC color profile of a Sony monitor. The idea is for the default printed output to look similar to what would be displayed on the screen. Naturally, a source profile for a Sony monitor is needed to do this. cocostiff and cocogif also accept, as a command-line argument, a source profile that overrides the default profile and, if so specified, any embedded source profiles. See the cocostiff(1) and cocogif(1) reference pages for details.ICC color profiles are stored in the /var/cms/profiles directory. cocostiff and cocogif search this directory for any profile specified as a command-line argument and whose profile name does not include a full directory path.For further information on ICC color profiles, see the web page at http://www.color.org. Search the web using the search string "International Color Consortium" to find several other technical references and applications.LBL="" HELPID=""ID="24547"Color Rendering DictionariesColor Rendering Dictionaries are used to manage the color of PostScript files, such as ones produced by Adobe Photoshopname='trade' font=symbol charset=fontspecific code=228
descr='[trade]', that specify CIELAB-based color spaces. PostScript files, such as those generated by ShowCasename='trade' font=symbol charset=fontspecific code=228
descr='[trade]', that do not specify a CIELAB-based color space do not have color management.CRDs are stored in /usr/lib/print/data/CRDs. A specific CRD is typically specified using the -I option with psrip. CRDs can be modified for use with the -I option by adding text at the end of the CRD to define it as a resource. An example of this is the last few lines from the /usr/lib/print/data/CRDs/hp1600C.crd file:/1600CCRD exch /ColorRendering defineresource pop
%%EndResource
{/1600CCRD /ColorRendering findresource } stopped
{ (%%[ Warning: Color CRD not found ]%%\r\n) print flush }
{dup /DefaultColorRendering exch /ColorRendering defineresource pop
setcolorrendering } ifelseTipCRDs are usually binary files. If your editor can not edit the file, try using jot.If a CRD is not specified with -I, a default is used. Default CRDs are in the directory /usr/lib/print/data/psrip/Resource/ColorRendering. ColorCRD is the default color CRD and MonoCRD is the default for monochrome images.LBL="" HELPID=""ID="25614"Generating CRDs and ICC ProfilesWhen creating CRDs and ICC profiles, remember that many variables affect the color that is produced. These include the following:halftone screen or dithering (such as spot function or error diffusion)resolution (for example, 360 dpi or 720 dpi) paper type (plain, coated, transparencies, and so on)ink lot (changing inks can change output color)printer manufacturing variationsage of the printerssettings (draft, normal, presentation, microdot, and so on, depending on the printer)Handling every case would require a separate CRD and ICC profile for each of the various combinations. In practice, this is rarely done because it requires a large number of CRDs and ICC profiles. A common approach, used by Impressario 2.0, is to generate one or two CRDs and profiles using the highest resolution, best paper, and best settings for the printer in question. The idea is to generate the CRDs and profiles for the printer when it is set to print in its best presentation mode.Generating an ICC profile or a CRD typically consists of these steps:Generate a test pattern containing a large number of color samples (say, 300 to 500).Measure the color samples using a Colorimeter.Generate several profiles and CRDs (for shadows, for highlights, and so on.)Print sample images using the various CRDs and profiles, and select a preferred set.Update the model file to use the preferred set.This process requires specific software tools (and a lot of time). Impressario 2.0 does not include these tools, but third-party solutions are available. (If you use a third-party service or software package to generate ICC profiles or CRDs you should verify that you have the right to re-distribute them.)NoteColorSynergy« software by Candela generated all the CRDs and many of the ICC profiles for Impressario 2.0. A ColorTronname='trade' font=symbol charset=fontspecific code=228
descr='[trade]' colorimeter from Light Source was the input measuring device. For more information about these products contact:COLUMNS="2"LEFT="0" WIDTH="168"Candela, Ltd.LEFT="175" WIDTH="165"Light Source Computer Images, Inc.LEFT="0" WIDTH="168"1676 East Cliff RoadLEFT="175" WIDTH="165"17 E. Sir Francis Drake Suite 100LEFT="0" WIDTH="168"Burnsville, MN 55337-1300LEFT="175" WIDTH="165"Larkspur, CA 94939LEFT="0" WIDTH="168"612 894-8890LEFT="175" WIDTH="165"415 925-4200LEFT="0" WIDTH="168"612 894-8840 (fax)LEFT="175" WIDTH="165"415 461-8011 (fax)LEFT="0" WIDTH="168"LEFT="175" WIDTH="165"URL: http://www.ls.comAs a final step, look at the way ICC profiles and CRDs are used in the model file /var/spool/lp/model/deskjetII_model. At the beginning of this file, default ICC profiles and CRDs are set for every printer. When the script is run, it calls the function get_icc_crd_name() to determine names for the ICC profile and CRD based on the printer model, paper type, and halftone being used. For example, if the printer is an HP DeskJet 1600C, get_icc_crd_name() returns two of the following names (one for an ICC profile, the other for a CRD):COLUMNS="2"LEFT="0" WIDTH="184"ICC Profile NameLEFT="190" WIDTH="184"CRD NameLEFT="0" WIDTH="184"HP_DeskJet_1600C_special_spot.pfLEFT="190" WIDTH="184"HP_DeskJet_1600C_special_spot.crdLEFT="0" WIDTH="184"HP_DeskJet_1600C_special_diffused.pfLEFT="190" WIDTH="184"HP_DeskJet_1600C_special_diffused.crdLEFT="0" WIDTH="184"HP_DeskJet_1600C_glossy_spot.pfLEFT="190" WIDTH="184"HP_DeskJet_1600C_glossy_spot.crdLEFT="0" WIDTH="184"HP_DeskJet_1600C_glossy_diffused.pfLEFT="190" WIDTH="184"HP_DeskJet_1600C_glossy_diffused.crdIt is the command returned by fileconvert, later in the model file, that determines whether the ICC profile or CRD is used. If the file to be printed is a raster image, color correction is performed using an ICC profile. If the HP 1600C is using glossy paper and error diffusion, and if an ICC profile in the /var/cms/profiles directory has the name HP_DeskJet_1600C_glossy_diffused.pf, the model file will find and use it. Otherwise it uses a default. After color correction, the file to be printed is converted to a PostScript file that is not CIELAB-based, and the PostScript file is sent to the PostScript interpreter.If the file to be printed is already PostScript, it is sent directly to the PostScript interpreter where a CRD is then applied if the file is CIELAB-based. As before, a default CRD is used if one with the proper name is not found. Notice that a CRD is never used on a PostScript file that has undergone color correction with an ICC profile.If you implement a function similar to get_icc_crd_name(), you should document the ICC profiles and CRD names that the driver recognizes. This allows users who create their own ICC profiles and CRDs to install them in the correct directories using the correct names. The goal is to enable users to supply ICC profiles and CRDs specific to the printers, inks, paper stocks, and so on in their environment.LBL="H"ID="38738"Using the Adobe Configurable PostScript InterpreterPlease note that Impressario Version 2.0 and the Impressario Developer's Kit (collectively, "IMPR") includes Adobe Systems, Inc. Configurable PostScript Interpreter ("CPSI"), also known as "psrip,"and is subject to the restrictions set forth below, as well as those set forth in the Silicon Graphics, Inc. Software License Agreement that accompanies Impressario Version 2.0.IMPR may be used to develop device drivers for any of the output devices specified in IDREF="22139" TYPE="TABLE"Table H-1.COLUMNS="2"LBL="H-1"Table H-1 ID="22139"Permitted IMPR Device DriversLEFT="0" WIDTH="118"Company/ManufacturedLEFT="125" WIDTH="243"Designated Output DeviceLEFT="0" WIDTH="118"Canon«LEFT="125" WIDTH="243"CJ-10LEFT="0" WIDTH="118"EpsonLEFT="125" WIDTH="243"Color Stylus, Stylus Pro, Stylus Pro XL, Color Stylus II, Color
descr='[trade]' CH7214,ColorPoint 2 CH7204-RSFLEFT="0" WIDTH="118"Tektronix«LEFT="125" WIDTH="243"Phaser« II SX, Phaser III RX, Phaser 300 RX,Phaser II SD, Phaser II SDXIMPR may be used to develop device drivers for any output device not listed in item 1 above, provided that such output device has a retail price of less than three thousand five hundred dollars ($3,500) U.S., and has an image data content of less then or equal to 600 bytes per inch, where image data content is determined by the formula below:Image data Content (Bytes/Inch) = (Mres x B x C) / 8whereMres = Maximum device resolution in pixels per inch
B = number of bits per colorant (the -B option to psrip)
C = number of colorants per pixel (RGB would be 3, CMYK 4, etc.)NoteIF YOUR DRIVER DOES NOT MEET THE REQUIREMENTS SET FORTH ABOVE THEN YOU DO NOT HAVE THE RIGHT TO USE OR DISTRIBUTE SUCH DRIVER IN CONJUNCTION WITH CPSI AS CONTAINED IN IMPR. IF YOU WISH TO REQUEST ADDITIONAL RIGHTS PLEASE CONTACT:Silicon Graphics, Inc.Digital Media Systems DivisionLegal Department2011 North Shoreline Blvd.Mountain View, CA 94043415 960-1980URL: http://www.sgi.comGlossaryID="gloss1"APIID="gloss2"Application program interface; a set of function calls for achieving some purpose.ID="gloss3"BSDID="gloss4"Berkeley Software Distribution.ID="gloss5"Chunky data formatID="gloss6"The original Impressario 1.0 data format; it has been made obsolete in favor of the Stream TIFF data format.CMY STIFF data format ID="gloss7"CMY data class is a subset of the CMYK class and differs from the CMYK class in a TIFF-compliant manner. See IDREF="76505" TYPE="TITLE""Generic STIFF File Structure" in Appendix A for detailed information.CMYK STIFF data formatID="gloss8"CMYK is a TIFF data format extension. See IDREF="76505" TYPE="TITLE""Generic STIFF File Structure" in Appendix A for detailed information. CMYK stands for cyan, magenta, yellow, and black, the subtractive color process primaries.CPSI ID="gloss9"Configurable PostScript Interpreter. Licensed from Adobe Systems, Inc., it is the foundation of psrip.File Type Rules (FTR)ID="gloss10"A database that is one of the three key components of the Impressario file conversion pipeline. These rules are well-documented in the Indigo Magic Desktop Integration Guide, available as an online book and installable from your IRIX CD.filter/driver specificationID="gloss11"SeeIDREF="77047" TYPE="TITLE""The Filter/Driver Specification and psrip" in Chapter 3.FTRID="gloss12"See File Type Rules.generic scanner interfaceID="gloss13"An interface between application programs and scanner drivers. See IDREF="59965" TYPE="TITLE"Chapter 9, "Generic Scanner Interface," for additional information.GIFID="gloss14"Graphics Interchange Format. A format for storing multibit images and graphics.glpID="gloss15"A graphical end-user interface for submitting print jobs from applications. See the glp(1) reference page for additional information.gscanID="gloss16"A graphical end-user interface for using scanners. See the gscan(1) reference page for additional information.GUIID="gloss17"Graphical user interface.ImpressarioID="gloss18"A visual printing and scanning environment for IRIS workstations.JPEGID="gloss19"Joint Photographic Experts Group. A file format that contains a JPEG data stream.libimpID="gloss20"A C application program interface (API) for reading and writing Silicon Graphics Image Format files.libpodID="gloss21"A C application program interface to the printer object database (POD).libprintuiID="gloss22"A graphical user interface (GUI) printing library.libscanID="gloss23"A C application program interface for scanning.libspoolID="gloss24"A C application program interface to the UNIX printer spooling system.libstiffID="gloss25"A C-language API for reading and writing Stream TIFF files.lp commandID="gloss26"The System V release 3 command to send a print job to the printer. See the lp(1) reference page.lpr commandID="gloss27"The BSD command to send a print job to a printer. See the lpr(1) reference page.lpsched command ID="gloss28"The System VR3 spooler job scheduler. Not invoked by end users.packed data formatID="gloss29"Bitmapped data organized by pixel, with all color components for each pixel adjacent. For example: RGBRGBRGB. . .planar data formatID="gloss30"Bitmapped data organized by color "plane," with all pixels arranged in planes of component colors, all components of one color, then another, and so on.PCDID="gloss31"Kodak Photo CD. Files using Eastman Kodak's proprietary format for storing digital images.plotter formatID="gloss32"A raster-based page-description language, most commonly HPGL or some variant.PODID="gloss33"See printer object database.PostScript printerID="gloss34"A printer with a built-in PostScript interpreter. It prints only PostScript files.PPMID="gloss35"Portable Pixmap Utilities. A format used in color bitmap file conversion.print clientID="gloss36"Any system other than the print server that wishes to use a printer.print serverID="gloss37"The system that controls a printer.PrintBoxID="gloss38"A graphical end-user interface for submitting print jobs from applications. See the libprintui(3) reference page for additional information.Printer ManagerID="gloss39"A graphical end-user interface for managing and installing printers. See the reference page for additional information.printer model fileID="gloss40"A Bourne shell script that controls the filtering and printing of a set of files. Invoked by the lpsched command. See IDREF="35103" TYPE="TITLE"Chapter 4, "Printer Model Files."<printer name>.configID="gloss41"A configuration file representing the capabilities of the printer. The .config file is part of the printer object database (POD).<printer name>.logID="gloss42"The printer log file for the specified printer. The .log file is part of the printer object database (POD).<printer name>.statusID="gloss43"A status file indicating the current printing state. The .status file is part of the printer object database (POD).printer object database (POD)ID="gloss44"The POD contains information on the current configuration, status, and job history of a single printer. It is the central database used by all printing filters and is maintained by each driver. See IDREF="64689" TYPE="TITLE"Appendix C, "Printer Object Database (POD) File Formats," for detailed information.printersID="gloss45"See Printer Manager.PrintPanelID="gloss46"An alias for glp, a graphical end-user interface for modifying printer settings. See the glp(1) reference page for additional information.PrintStatusID="gloss47"A graphical end-user interface for checking printer status. See the PrintStatus(1) reference page for additional information.raster printerID="gloss48"A printer that accepts only bitmap image data.scanner driverID="gloss49"A program that interfaces with a scanner. See IDREF="64426" TYPE="TITLE"Chapter 7, "Scanner Drivers," for additional information.scannersID="gloss50"A graphical end-user interface for installing and managing scanners. See the scanners(1) reference page for additional information.SGIID="gloss51"Silicon Graphics, Inc. image file format. Format for storing black-and-write, color RGB, and color RGB with alpha channel images.spooling system APIID="gloss52"See libspool and libprintui.STIFFID="gloss53"Stream TIFF is a subset of the Tagged Image File Format (TIFF) originally developed by Aldus Corporation. See IDREF="68392" TYPE="TITLE"Appendix A, "Stream TIFF Data Format," for more information.System V spooler interfaceID="gloss54"See lp command and lpsched command.Tagged Image File FormatID="gloss55"The Tagged Image File Format (TIFF) originally developed by Aldus Corporation. See IDREF="68392" TYPE="TITLE"Appendix A, "Stream TIFF Data Format," for more information.TIFFID="gloss56"See Tagged Image File Format.YMC data formatID="gloss57"A data class similar to the CMY class with the exception that data is organized as YMC instead of CMY. YMC stands for yellow, magenta, and cyan.YMCK data formatID="gloss58"A class similar to CMYK except that data is organized as YMCK instead of CMYK. YMCK stands for yellow, magenta, cyan, and black.active icons subsystemIDREF="chap425"Printer TypeActive Status PathIDREF="apenC14"Active Status Pathadding a CONVERT ruleIDREF="chap1213"Adding a CONVERT Ruleadding a new filetype to ImpressarioIDREF="chap1210"Adding a New Filetype to ImpressarioAdvanceFeeder functionIDREF="chap724"AdvanceFeeder() FunctionAPIIDREF="gloss2"GlossarylibpodIDREF="chap174"libpod APIlibprintuiIDREF="chap170"libprintui APIlibspoolIDREF="chap167"libspool APIAPIs to spooling systemsIDREF="chap63"The libspool LibraryIDREF="chap162"Printing Application Programming Interfacesapplication developersprogramming interfaceIDREF="chap155"Printing Application Programming InterfacesIDREF="chap165"Printing Application Programming Interfacesapplication programming interfaceIDREF="gloss3"Glossaryapplication programming interfacesIDREF="chap154"Printing Application Programming InterfacesIDREF="chap164"Printing Application Programming Interfacesapplication/driver functionsIDREF="chap913"Application/Driver Rendezvous FunctionsAT&T System V printer spooling systemIDREF="intro5"About This GuideaudienceIDREF="intro16"AudienceAvailable Fonts optionIDREF="apenC15"Available Fontsbanner pageIDREF="chap411"Printing Banner Pagebanner pagesIDREF="chap439"Printer-Specific Banner PageBerkeley Software DistributionIDREF="gloss5"GlossaryBlack Substitute optionIDREF="apenC17"Black Substitutebold syntax conventionIDREF="intro35"Conventions Used in This GuidebracketsIDREF="intro41"Conventions Used in This GuideBSDIDREF="gloss4"GlossaryBSD spooling systemIDREF="chap156"Printing Application Programming InterfacescallbacksIDREF="chap618"Add CallbacksCentronics interfacesIDREF="chap421"Device InterfaceCHUNKY file formatIDREF="gloss6"GlossaryCMY data formatIDREF="apenA14"Generic STIFF File StructureCMY STIFF data formatIDREF="gloss7"GlossaryCMYK data formatIDREF="apenA13"Generic STIFF File StructureCMYK STIFF data formatIDREF="gloss8"GlossaryColor Adjustment optionIDREF="apenC19"Color Adjustmentcolor space conversion functionsIDREF="apenB35"Color Space Conversion FunctionsColorPostScriptIDREF="chap430"Printer TypeColorRasterIDREF="chap432"Printer Type.configIDREF="gloss41"Glossaryconfig file optionActive Status PathIDREF="apenC13"Active Status PathAvailable FontsIDREF="apenC16"Available FontsBlack SubstituteIDREF="apenC18"Black SubstituteColor AdjustmentIDREF="apenC20"Color AdjustmentCost per PageIDREF="apenC22"Cost per PageDefault CAIDREF="apenC24"Default CADefault ISIDREF="apenC26"Default ISDefault MTIDREF="apenC28"Default MTDefault QMIDREF="apenC30"Default QMDriver PathIDREF="apenC31"Driver PathError Retry WaitIDREF="apenC34"Error Retry WaitInput SourceIDREF="apenC36"Input SourceLocation CodeIDREF="apenC37"Location CodeManual CapableIDREF="apenC40"Manual CapableMaximum AddrIDREF="apenC42"Maximum AddrMaximum Print AreaIDREF="apenC44"Maximum Print AreaMedia StandardIDREF="apenC46"Media StandardMedia TypeIDREF="apenC48"Media TypeMedia WaitIDREF="apenC50"Media WaitMinimum AddrIDREF="apenC52"Minimum AddrMinimum Print AreaIDREF="apenC54"Minimum Print AreaNumber of ColorsIDREF="apenC56"Number of ColorsPhysical LocationIDREF="apenC57"Physical LocationPort PathIDREF="apenC59"Port PathPrinter ClassIDREF="apenC61"Printer ClassPrinter ModelIDREF="apenC63"Printer ModelPrinter OptionsIDREF="apenC65"Printer OptionsQuality ModesIDREF="apenC68"Quality ModesResolutionIDREF="apenC70"ResolutionSize Table EntryIDREF="apenC72"Size Table EntryStatus Update WaitIDREF="apenC73"Status Update WaitTechnologyIDREF="apenC75"TechnologyTime per PageIDREF="apenC78"Time per Pageconfiguration fileIDREF="chap622"POD FilesIDREF="chap139"Step 2: Provide POD Files (Required)configuring the Impressario softwareIDREF="chap240"Configuring the Impressario Softwareconnecting the printer or scannerIDREF="chap214"Connecting the Printer or Scannercopies, number ofIDREF="chap47"Command-Line ArgumentsCost per Page optionIDREF="apenC21"Cost per Pagecourier syntax conventionIDREF="intro39"Conventions Used in This GuideIDREF="intro37"Conventions Used in This GuideCPSIIDREF="gloss9"Glossarycreating a graphical options panelIDREF="chap150"Step 5: Create Graphical Options Panel (Recommended)creating a model fileIDREF="chap146"Step 3: Create Model File (Required)customized banner pagesIDREF="chap437"Printer-Specific Banner Pagedata formatSTIFFIDREF="apenA1"Stream TIFF Data Formatdata packing functionsIDREF="apenB16"Data Packing Functionsdata structureSCANINFOIDREF="chap713"SCANINFO Data StructureSCANPARAMSIDREF="chap715"SCANPARAMS Data Structuredata structuresscannerIDREF="chap74"Header Filesdebug switchIDREF="chap435"Debug RoutineDefault CA optionIDREF="apenC23"Default CADefault IS optionIDREF="apenC25"Default ISDefault MT optionIDREF="apenC27"Default MTDefault QM optionIDREF="apenC29"Default QMDeleteScanner functionIDREF="chap734"DeleteScanner() Functiondeskjet_model.guiIDREF="chap510"Graphical Options Panel Namingdeveloping a printer driverIDREF="chap135"Step 1: Develop Printer Driver (Required)device interfaceIDREF="chap416"Device Interfacedirectoryexample POD filesIDREF="chap145"Step 2: Provide POD Files (Required)model filesIDREF="chap147"Step 3: Create Model File (Required)printer filter programsIDREF="chap149"Step 4: Provide Data Filters (As Needed)disk space requirementsIDREF="chap210"Disk Space Requirementsdocument feeder functionsIDREF="chap965"Document Feeder FunctionsDoScan functionIDREF="chap720"DoScan() FunctiondriverIDREF="chap115"Packaging Impressario Printing SoftwareDriver PathIDREF="apenC32"Driver Pathdriver see also printer driversdevelopmentIDREF="chap32"Printer Driversdriver templatescannerIDREF="chap72"Header Filesengine-specific optionsIDREF="chap319"Reserved Optionsenhancing Impressario with plug-insIDREF="chap121"Enhancing Impressario With Plug-InsErrorIDREF="apenC98"Error, Warning, and Information Optionserror handling functionsIDREF="apenB21"Error Handling FunctionsError Retry Wait optionIDREF="apenC33"Error Retry WaiteventsIDREF="chap736"Eventsfast path for textIDREF="chap442"Fast Path for TextFeederReady functionIDREF="chap726"FeederReady() Functionfile conversion utilityIDREF="chap127"File Conversion Utilityfile extensions.configIDREF="chap143"Step 2: Provide POD Files (Required).logIDREF="chap142"Step 2: Provide POD Files (Required).statusIDREF="chap144"Step 2: Provide POD Files (Required)File Type RulesIDREF="gloss10"GlossaryIDREF="chap124"File Type Rulesfileconvert man pageIDREF="apenF18"Reference Pagesfileconvert utilityIDREF="chap128"File Conversion UtilityIDREF="chap129"File Conversion Utilityfilter functionsIDREF="apenB106"Filter Functionsfilter/driverspecificationIDREF="chap312"The Filter/Driver Specification and psripfilter/driver specificationIDREF="gloss11"Glossaryfiltering optionsIDREF="chap441"Printer-Specific Filtering OptionsFindScanners functionIDREF="chap730"FindScanners() FunctionFTRIDREF="gloss12"GlossaryIDREF="chap123"How the Impressario File Conversion Pipeline WorksfunctionAdvanceFeederIDREF="chap725"AdvanceFeeder() FunctionDeleteScannerIDREF="chap735"DeleteScanner() FunctionDoScanIDREF="chap721"DoScan() FunctionFeederReadyIDREF="chap727"FeederReady() FunctionFindScannersIDREF="chap731"FindScanners() FunctionimpClampRowIDREF="apenB91"impZeroRow(), impInitRow(), impCopyRow(), impSAddRow(), impVAddRow(), impSSubRow(), impVSubRow(), impSMulRow(), impSDivRow(), impClampRow() FunctionsimpCloseIDREF="apenB13"impOpen(), impOpenFd(), impClose(), and impCloseFd() FunctionsimpCloseFdIDREF="apenB15"impOpen(), impOpenFd(), impClose(), and impCloseFd() FunctionsimpCMYKtoRGBIDREF="apenB65"impRGBtoCMYK(), impRGBtoDevCMYK(), impCMYKtoRGB() FunctionsimpCMYtoRGBIDREF="apenB47"impRGBtoCMY(), impCMYtoRGB() FunctionsimpCopyRowIDREF="apenB77"impZeroRow(), impInitRow(), impCopyRow(), impSAddRow(), impVAddRow(), impSSubRow(), impVSubRow(), impSMulRow(), impSDivRow(), impClampRow() FunctionsimpCreateZoomIDREF="apenB94"impCreateZoom(), impDestroyZoom(), impResetZoom(), impZoomRow() FunctionsimpDestroyZoomIDREF="apenB96"impCreateZoom(), impDestroyZoom(), impResetZoom(), impZoomRow() FunctionsimpErrorStringIDREF="apenB25"impPerror() and impErrorString() FunctionsimpHSVtoRGB functionIDREF="apenB68"impRGBtoHSV(), impHSVtoRGB() FunctionsimpInitRowIDREF="apenB75"impZeroRow(), impInitRow(), impCopyRow(), impSAddRow(), impVAddRow(), impSSubRow(), impVSubRow(), impSMulRow(), impSDivRow(), impClampRow() FunctionsimpKtoRGBIDREF="apenB43"impRGBtoK(), impKtoRGB() FunctionsimpOpenIDREF="apenB9"impOpen(), impOpenFd(), impClose(), and impCloseFd() FunctionsimpOpenFdIDREF="apenB11"impOpen(), impOpenFd(), impClose(), and impCloseFd() FunctionsimpPackRowIDREF="apenB18"impPackRow() and impUnpackRow() FunctionsimpPerrorIDREF="apenB23"impPerror() and impErrorString() FunctionsimpReadRowIDREF="apenB28"impReadRow(), impReadRowB(), impWriteRow(), and impWriteRowB() FunctionsimpReadRowBIDREF="apenB30"impReadRow(), impReadRowB(), impWriteRow(), and impWriteRowB() FunctionsimpResetZoomIDREF="apenB98"impCreateZoom(), impDestroyZoom(), impResetZoom(), impZoomRow() FunctionsimpRGBtoCMYIDREF="apenB45"impRGBtoCMY(), impCMYtoRGB() FunctionsimpRGBtoCMYKIDREF="apenB61"impRGBtoCMYK(), impRGBtoDevCMYK(), impCMYKtoRGB() FunctionsimpRGBtoDevCMYKIDREF="apenB63"impRGBtoCMYK(), impRGBtoDevCMYK(), impCMYKtoRGB() FunctionsimpRGBtoHLSIDREF="apenB70"impRGBtoHLS(), impHLStoRGB() FunctionsimpRGBtoHSVIDREF="apenB67"impRGBtoHSV(), impHSVtoRGB() FunctionsimpRGBtoKIDREF="apenB41"impRGBtoK(), impKtoRGB() FunctionsimpRGBtoWIDREF="apenB37"impRGBtoW(), impWtoRGB() FunctionsimpRGBtoYCbCrIDREF="apenB57"impRGBtoYCbCr(), impYCbCrtoRGB() FunctionsimpRGBtoYIQIDREF="apenB49"impRGBtoYIQ(), impYIQtoRGB() FunctionsimpRGBtoYUVIDREF="apenB53"impRGBtoYUV(), impYUVtoRGB() FunctionsimpSAddRowIDREF="apenB79"impZeroRow(), impInitRow(), impCopyRow(), impSAddRow(), impVAddRow(), impSSubRow(), impVSubRow(), impSMulRow(), impSDivRow(), impClampRow() FunctionsimpSDivRowIDREF="apenB89"impZeroRow(), impInitRow(), impCopyRow(), impSAddRow(), impVAddRow(), impSSubRow(), impVSubRow(), impSMulRow(), impSDivRow(), impClampRow() FunctionsimpSMulRowIDREF="apenB87"impZeroRow(), impInitRow(), impCopyRow(), impSAddRow(), impVAddRow(), impSSubRow(), impVSubRow(), impSMulRow(), impSDivRow(), impClampRow() FunctionsimpSSubRowIDREF="apenB83"impZeroRow(), impInitRow(), impCopyRow(), impSAddRow(), impVAddRow(), impSSubRow(), impVSubRow(), impSMulRow(), impSDivRow(), impClampRow() FunctionsimpUnpackRowIDREF="apenB20"impPackRow() and impUnpackRow() FunctionsimpVAddRowIDREF="apenB81"impZeroRow(), impInitRow(), impCopyRow(), impSAddRow(), impVAddRow(), impSSubRow(), impVSubRow(), impSMulRow(), impSDivRow(), impClampRow() FunctionsimpVSubRowIDREF="apenB85"impZeroRow(), impInitRow(), impCopyRow(), impSAddRow(), impVAddRow(), impSSubRow(), impVSubRow(), impSMulRow(), impSDivRow(), impClampRow() FunctionsimpWriteRowIDREF="apenB32"impReadRow(), impReadRowB(), impWriteRow(), and impWriteRowB() FunctionsimpWriteRowBIDREF="apenB34"impReadRow(), impReadRowB(), impWriteRow(), and impWriteRowB() FunctionsimpWtoRGBIDREF="apenB39"impRGBtoW(), impWtoRGB() FunctionsimpYCbCrtoRGBIDREF="apenB59"impRGBtoYCbCr(), impYCbCrtoRGB() FunctionsimpYIQtoRGBIDREF="apenB51"impRGBtoYIQ(), impYIQtoRGB() FunctionsimpZeroRowIDREF="apenB73"impZeroRow(), impInitRow(), impCopyRow(), impSAddRow(), impVAddRow(), impSSubRow(), impVSubRow(), impSMulRow(), impSDivRow(), impClampRow() FunctionsimpZoomRowIDREF="apenB100"impCreateZoom(), impDestroyZoom(), impResetZoom(), impZoomRow() FunctionsInstallScannerIDREF="chap733"InstallScanner() FunctionOpenScannerIDREF="chap717"OpenScanner() FunctionPrintIDIDREF="chap729"PrintID() FunctionSCAbortIDREF="chap960"SCAbort() FunctionSCBandRGB8ToPixelRGB8IDREF="apenE78"SCBandRGB8ToPixelRGB8() FunctionIDREF="apenE77"SCBandRGB8ToPixelRGB8() FunctionSCCloseIDREF="chap921"SCClose() FunctionSCCreateQueueIDREF="apenE86"Queue Manipulating FunctionsIDREF="apenE96"SCCreateQueue() FunctionIDREF="apenE97"SCCreateQueue() FunctionSCCreateZoomMapIDREF="apenE59"SCCreateZoomMap() FunctionIDREF="apenE60"SCCreateZoomMap() FunctionSCDataReadyIDREF="chap954"SCDataReady() FunctionSCDefaultScannerNameIDREF="chap933"SCDefaultScannerName() FunctionSCDequeueIDREF="apenE105"SCDequeue() FunctionIDREF="apenE106"SCDequeue() FunctionIDREF="apenE92"Queue Manipulating FunctionsSCDestroyQueueIDREF="apenE100"SCDestroyQueue() FunctionIDREF="apenE88"Queue Manipulating FunctionsIDREF="apenE99"SCDestroyQueue() FunctionSCDestroyZoomMapIDREF="apenE63"SCDestroyZoomMap() FunctionIDREF="apenE62"SCDestroyZoomMap() FunctionSCEndScanEntIDREF="chap927"SCEndScanEnt() FunctionSCEnqueueIDREF="apenE101"SCEnqueue() FunctionIDREF="apenE89"Queue Manipulating FunctionsSCErrorStringIDREF="chap912"SCErrorString() FunctionSCFeederAdvanceIDREF="chap971"SCFeederAdvance() FunctionSCFeederGetFlagsIDREF="chap967"SCFeederGetFlags() FunctionSCFeederReadyIDREF="chap973"SCFeederReady() FunctionSCFeederSetFlagsIDREF="chap969"SCFeederSetFlags() FunctionSCGetDataTypesIDREF="chap943"SCGetDataTypes() FunctionSCGetFDIDREF="chap956"SCGetFD() FunctionSCGetMinMaxResIDREF="chap938"SCGetMinMaxRes() FunctionSCGetPageSizeIDREF="chap941"SCGetPageSize() FunctionSCGetScanEntIDREF="chap925"SCGetScanEnt() FunctionSCGetScanLineIDREF="chap952"SCGetScanLine() FunctionSCGetScannerResIDREF="chap936"SCGetScannerRes() FunctionSCGetScanSizeIDREF="chap948"SCGetScanSize() FunctionSCGetStatusIDREF="chap962"SCGetStatus() FunctionSCGetStatusFDIDREF="chap964"SCGetStatusFD() FunctionSCGrey8ToMonoIDREF="apenE81"SCGrey8ToMono() FunctionIDREF="apenE80"SCGrey8ToMono() FunctionSCN_ABORTIDREF="apenE51"SCN_ABORT() FunctionIDREF="apenE52"SCN_ABORT() FunctionSCN_DIEIDREF="apenE55"SCN_DIE() FunctionIDREF="apenE54"SCN_DIE() FunctionSCN_FEEDERADVANCEIDREF="apenE39"SCN_FEEDERADVANCE() FunctionSCN_FEEDERGETFLAGSIDREF="apenE31"SCN_FEEDERGETFLAGS() FunctionIDREF="apenE30"SCN_FEEDERGETFLAGS() FunctionSCN_FEEDERREADYIDREF="apenE37"SCN_FEEDERREADY() FunctionIDREF="apenE36"SCN_FEEDERREADY() FunctionSCN_FEEDERSETFLAGSIDREF="apenE33"SCN_FEEDERSETFLAGS() FunctionIDREF="apenE34"SCN_FEEDERSETFLAGS() FunctionSCN_GETSIZEIDREF="apenE46"SCN_GETSIZE() FunctionIDREF="apenE45"SCN_GETSIZE() FunctionSCN_INITOKIDREF="apenE9"SCN_INITOK() FunctionIDREF="apenE10"SCN_INITOK() FunctionSCN_MINMAXRESIDREF="apenE15"SCN_MINMAXRES() FunctionIDREF="apenE16"SCN_MINMAXRES() FunctionSCN_NRESIDREF="apenE19"SCN_NRES() FunctionIDREF="apenE18"SCN_NRES() FunctionSCN_NTYPESIDREF="apenE25"SCN_NTYPES() FunctionIDREF="apenE24"SCN_NTYPES() FunctionSCN_PAGESIZEIDREF="apenE13"SCN_PAGESIZE() FunctionIDREF="apenE12"SCN_PAGESIZE() FunctionSCN_RESIDREF="apenE21"SCN_RES() FunctionIDREF="apenE22"SCN_RES() FunctionSCN_SCANIDREF="apenE48"SCN_SCAN() FunctionIDREF="apenE49"SCN_SCAN() FunctionSCN_SETUPIDREF="apenE42"SCN_SETUP() FunctionIDREF="apenE43"SCN_SETUP() FunctionSCN_TYPESIDREF="apenE27"SCN_TYPES() FunctionIDREF="apenE28"SCN_TYPES() FunctionSCOpenIDREF="chap915"SCOpen() FunctionSCOpenFileIDREF="chap919"SCOpenFile() FunctionSCOpenScreenIDREF="chap917"SCOpenScreen() FunctionSCPerrorIDREF="chap910"SCPerror() FunctionSCQueueSetExitIDREF="apenE108"SCQueueSetExit() FunctionIDREF="apenE109"SCQueueSetExit() FunctionIDREF="apenE94"Queue Manipulating FunctionsSCScanIDREF="chap950"SCScan() FunctionSCScanFDIDREF="chap958"SCScanFD() FunctionSCScannerNameIDREF="chap931"SCScannerEnt() FunctionIDREF="chap929"SCScannerName() FunctionSCSetScanEntIDREF="chap923"SCSetScanEnt() FunctionSCSetupIDREF="chap946"SCSetup() FunctionSCZoomRow1IDREF="apenE66"SCZoomRow1() FunctionIDREF="apenE65"SCZoomRow1() FunctionSCZoomRow24IDREF="apenE72"SCZoomRow24() FunctionIDREF="apenE71"SCZoomRow24() FunctionSCZoomRow32IDREF="apenE74"SCZoomRow32() FunctionIDREF="apenE75"SCZoomRow32() FunctionSCZoomRow8IDREF="apenE68"SCZoomRow8() FunctionIDREF="apenE69"SCZoomRow8() FunctionSetFeederFlagsIDREF="chap723"SetFeederFlags() FunctionSetupScanIDREF="chap719"SetupScan() Functiongeneral filter/driver architectureIDREF="chap160"Printing Application Programming Interfacesgeneral interest man pagesIDREF="apenF1"Reference Pagesgeneric scanner APIIDREF="chap82"Overviewgeneric scanner interfaceIDREF="gloss13"GlossaryIDREF="chap91"Generic Scanner Interfacegeneric STIFF file structureIDREF="apenA11"Printing-Specific STIFFgetoptsIDREF="chap310"Do the Initial ProcessingGIFIDREF="gloss14"GlossaryglossaryIDREF="gloss1"GlossaryglpIDREF="chap178"glp (PrintPanel)IDREF="chap190"Printing Application DevelopmentIDREF="gloss15"GlossaryprogramIDREF="chap513"Invocation by the PrintBox Widgetglp man pageIDREF="apenF4"Reference Pagesgraphical interfacePrintBoxIDREF="chap110"OverviewprintersIDREF="chap18"OverviewIDREF="chap16"OverviewIDREF="chap14"OverviewPrintPanelIDREF="chap15"OverviewPrintStatusIDREF="chap17"OverviewscannersIDREF="chap111"Overviewgraphical options panelIDREF="chap51"Printer Graphical Options Panelaction areaIDREF="chap55"Graphical Options Panel LayoutdevelopmentIDREF="chap57"Graphical Options Panel DevelopmentinstallationIDREF="chap511"Graphical Options Panel InstallationinvocationIDREF="chap512"Invocation by the PrintBox WidgetlayoutIDREF="chap54"Graphical Options Panel LayoutnamingIDREF="chap59"Graphical Options Panel Namingoptions handlingIDREF="chap56"Options HandlingterminationIDREF="chap515"Termination by the PrintBox Widgetgraphical options panel programIDREF="chap117"Packaging Impressario Printing Softwaregraphical options panel resource fileIDREF="chap118"Packaging Impressario Printing Softwaregraphical user interfaceIDREF="intro10"About This Guidegrelnotes man pageIDREF="intro2"About This GuidegscanIDREF="gloss16"Glossarygscan man pageIDREF="apenA5"Stream TIFF Data FormatIDREF="apenF14"Reference PagesGUIIDREF="gloss17"GlossaryIDREF="intro11"About This Guidehardware interfacesIDREF="chap419"Device Interfaceheader filesscannerIDREF="chap76"Header Fileshow the file conversion pipeline worksIDREF="chap122"How the Impressario File Conversion Pipeline Workshow to use this guideIDREF="intro29"How to Use This Guideimage access functionsIDREF="apenB6"Image Access Functionsimage I/O functionsIDREF="apenB26"Image I/O FunctionsimpClampRow functionIDREF="apenB90"impZeroRow(), impInitRow(), impCopyRow(), impSAddRow(), impVAddRow(), impSSubRow(), impVSubRow(), impSMulRow(), impSDivRow(), impClampRow() FunctionsimpClose functionIDREF="apenB12"impOpen(), impOpenFd(), impClose(), and impCloseFd() FunctionsimpCloseFd functionIDREF="apenB14"impOpen(), impOpenFd(), impClose(), and impCloseFd() FunctionsimpCMYKtoRGB functionIDREF="apenB64"impRGBtoCMYK(), impRGBtoDevCMYK(), impCMYKtoRGB() FunctionsimpCMYtoRGB functionIDREF="apenB46"impRGBtoCMY(), impCMYtoRGB() FunctionsimpCopyRow functionIDREF="apenB76"impZeroRow(), impInitRow(), impCopyRow(), impSAddRow(), impVAddRow(), impSSubRow(), impVSubRow(), impSMulRow(), impSDivRow(), impClampRow() FunctionsimpCreateZoomIDREF="apenB102"impCreateZoom(), impDestroyZoom(), impResetZoom(), impZoomRow() FunctionsimpCreateZoom functionIDREF="apenB93"impCreateZoom(), impDestroyZoom(), impResetZoom(), impZoomRow() FunctionsimpDestroyZoomIDREF="apenB104"impCreateZoom(), impDestroyZoom(), impResetZoom(), impZoomRow() FunctionsimpDestroyZoom functionIDREF="apenB95"impCreateZoom(), impDestroyZoom(), impResetZoom(), impZoomRow() FunctionsimpErrorString functionIDREF="apenB24"impPerror() and impErrorString() FunctionsimpHLStoRGB functionIDREF="apenB71"impRGBtoHLS(), impHLStoRGB() FunctionsIMPImage structureIDREF="apenB5"IMPImage StructureimpInitRow functionIDREF="apenB74"impZeroRow(), impInitRow(), impCopyRow(), impSAddRow(), impVAddRow(), impSSubRow(), impVSubRow(), impSMulRow(), impSDivRow(), impClampRow() FunctionsimpKtoRGB functionIDREF="apenB42"impRGBtoK(), impKtoRGB() FunctionsimpOpen functionIDREF="apenB8"impOpen(), impOpenFd(), impClose(), and impCloseFd() FunctionsIDREF="apenB7"impOpen() FunctionimpOpenFd functionIDREF="apenB10"impOpen(), impOpenFd(), impClose(), and impCloseFd() FunctionsimpPackRow functionIDREF="apenB17"impPackRow() and impUnpackRow() FunctionsimpPerror functionIDREF="apenB22"impPerror() and impErrorString() Functionsimpr_base.sw.il_imagesIDREF="chap29"Installation Software PrerequisitesimpReadRow functionIDREF="apenB27"impReadRow(), impReadRowB(), impWriteRow(), and impWriteRowB() FunctionsimpReadRowB functionIDREF="apenB29"impReadRow(), impReadRowB(), impWriteRow(), and impWriteRowB() FunctionsimpResetZoomIDREF="apenB105"impCreateZoom(), impDestroyZoom(), impResetZoom(), impZoomRow() FunctionsimpResetZoom functionIDREF="apenB97"impCreateZoom(), impDestroyZoom(), impResetZoom(), impZoomRow() FunctionsImpressarioIDREF="gloss18"GlossaryAPIs to spooling systemIDREF="chap161"Printing Application Programming Interfacesapplication programming interfacesIDREF="chap153"Printing Application Programming InterfacesIDREF="chap163"Printing Application Programming InterfacesarchitectureIDREF="chap11"Impressario ArchitectureprintingIDREF="chap133"Impressario Printing Architecturecomplianceprint driver developersIDREF="chap134"Compliance for Printer-Driver DevelopersoverviewIDREF="chap12"Overviewprinting application developmentIDREF="chap183"Printing Application Developmentprinting architectureIDREF="chap132"Impressario Printing ArchitecturesubsystemsIDREF="chap102"Testing Impressario Printing CompatibilityIDREF="chap24"Impressario ProductsImpressario 2.0IDREF="intro17"New FeaturesImpressario compliancefor scannersIDREF="chap191"Complying With the Impressario Scanning ArchitectureImpressario Developer's Kit softwareIDREF="chap22"Installing Impressario SoftwareImpressario man pageIDREF="apenF2"Reference PagesImpressario printing architectureIDREF="chap131"Impressario Printing ArchitectureImpressario release notesIDREF="intro1"About This GuideImpressario subsystemsIDREF="chap23"Impressario ProductsIDREF="chap101"Testing Impressario Printing CompatibilityimpRGBtoCMY functionIDREF="apenB44"impRGBtoCMY(), impCMYtoRGB() FunctionsimpRGBtoCMYK functionIDREF="apenB60"impRGBtoCMYK(), impRGBtoDevCMYK(), impCMYKtoRGB() FunctionsimpRGBtoDevCMYK functionIDREF="apenB62"impRGBtoCMYK(), impRGBtoDevCMYK(), impCMYKtoRGB() FunctionsimpRGBtoHLS functionIDREF="apenB69"impRGBtoHLS(), impHLStoRGB() FunctionsimpRGBtoHSV functionIDREF="apenB66"impRGBtoHSV(), impHSVtoRGB() FunctionsimpRGBtoK functionIDREF="apenB40"impRGBtoK(), impKtoRGB() FunctionsimpRGBtoW functionIDREF="apenB36"impRGBtoW(), impWtoRGB() FunctionsimpRGBtoYCbCr functionIDREF="apenB56"impRGBtoYCbCr(), impYCbCrtoRGB() FunctionsimpRGBtoYIQ functionIDREF="apenB48"impRGBtoYIQ(), impYIQtoRGB() FunctionsimpRGBtoYUV functionIDREF="apenB52"impRGBtoYUV(), impYUVtoRGB() FunctionsimpSAddRow functionIDREF="apenB80"impZeroRow(), impInitRow(), impCopyRow(), impSAddRow(), impVAddRow(), impSSubRow(), impVSubRow(), impSMulRow(), impSDivRow(), impClampRow() FunctionsIDREF="apenB78"impZeroRow(), impInitRow(), impCopyRow(), impSAddRow(), impVAddRow(), impSSubRow(), impVSubRow(), impSMulRow(), impSDivRow(), impClampRow() FunctionsimpSDivRow functionIDREF="apenB88"impZeroRow(), impInitRow(), impCopyRow(), impSAddRow(), impVAddRow(), impSSubRow(), impVSubRow(), impSMulRow(), impSDivRow(), impClampRow() FunctionsimpSMulRow functionIDREF="apenB86"impZeroRow(), impInitRow(), impCopyRow(), impSAddRow(), impVAddRow(), impSSubRow(), impVSubRow(), impSMulRow(), impSDivRow(), impClampRow() FunctionsimpSSubRow functionIDREF="apenB82"impZeroRow(), impInitRow(), impCopyRow(), impSAddRow(), impVAddRow(), impSSubRow(), impVSubRow(), impSMulRow(), impSDivRow(), impClampRow() FunctionsimpUnpackRow functionIDREF="apenB19"impPackRow() and impUnpackRow() FunctionsimpVSubRow functionIDREF="apenB84"impZeroRow(), impInitRow(), impCopyRow(), impSAddRow(), impVAddRow(), impSSubRow(), impVSubRow(), impSMulRow(), impSDivRow(), impClampRow() FunctionsimpWriteRow functionIDREF="apenB31"impReadRow(), impReadRowB(), impWriteRow(), and impWriteRowB() FunctionsimpWriteRowB functionIDREF="apenB33"impReadRow(), impReadRowB(), impWriteRow(), and impWriteRowB() FunctionsimpWtoRGB functionIDREF="apenB38"impRGBtoW(), impWtoRGB() FunctionsimpYCbCrtoRGB functionIDREF="apenB58"impRGBtoYCbCr(), impYCbCrtoRGB() FunctionsimpYIQtoRGB functionIDREF="apenB50"impRGBtoYIQ(), impYIQtoRGB() FunctionsimpYUVtoRGBIDREF="apenB55"impRGBtoYUV(), impYUVtoRGB() FunctionsimpYUVtoRGB functionIDREF="apenB54"impRGBtoYUV(), impYUVtoRGB() FunctionsimpZeroRow functionIDREF="apenB72"impZeroRow(), impInitRow(), impCopyRow(), impSAddRow(), impVAddRow(), impSSubRow(), impVSubRow(), impSMulRow(), impSDivRow(), impClampRow() FunctionsimpZoomRowIDREF="apenB103"impCreateZoom(), impDestroyZoom(), impResetZoom(), impZoomRow() FunctionsimpZoomRow functionIDREF="apenB99"impCreateZoom(), impDestroyZoom(), impResetZoom(), impZoomRow() FunctionsIndigo Magic desktopIDREF="chap28"Installation Software PrerequisitesInformationIDREF="apenC100"Error, Warning, and Information OptionsInput Source optionIDREF="apenC35"Input Sourceinstallation disk space requirementsIDREF="chap211"Disk Space Requirementssoftware prerequisitesIDREF="chap26"Installation Software Prerequisitesinstallation methodIDREF="chap212"Installing Impressarioinstallation software prerequisitesIDREF="chap27"Installation Software Prerequisitesinstallfoliofonts man pageIDREF="apenF24"Reference Pagesinstalling Impressario softwareIDREF="chap21"Installing Impressario SoftwareIDREF="chap213"Installing Impressario Softwareinstallpcfonts man pageIDREF="apenF26"Reference PagesInstallScanner functionIDREF="chap732"InstallScanner() FunctioninterfacesIDREF="chap418"Device InterfaceISO text filesIDREF="intro6"About This Guideitalics syntax conventionIDREF="intro33"Conventions Used in This Guidejobsequence ID numberIDREF="chap44"Command-Line ArgumentstitleIDREF="chap46"Command-Line ArgumentsJPEGIDREF="gloss19"GlossaryKCMY data formatIDREF="apenA17"Generic STIFF File StructurelaserjetIDREF="chap35"Printer Driver ExampleslibimpIDREF="apenB3"Library DescriptionIDREF="chap127"OverviewIDREF="gloss20"Glossarylibimp libraryIDREF="apenB101"impCreateZoom(), impDestroyZoom(), impResetZoom(), impZoomRow() Functionslibimp library functionsIDREF="apenB4"Library Functionslibimp man pageIDREF="apenF39"Reference PagesIDREF="apenF46"Reference PageslibpodIDREF="chap130"OverviewIDREF="chap136"Step 1: Develop Printer Driver (Required)IDREF="chap117"OverviewIDREF="chap189"Printing Application DevelopmentIDREF="chap175"libpod APIIDREF="gloss21"Glossarylibpod APIIDREF="chap173"libpod APIlibpod libraryIDREF="chap619"The libpod Librarycompiling programsIDREF="chap630"Compiling Programs With libpoddebuggingIDREF="chap631"Debugging With libpodfile parsing rulesIDREF="apenC11"Input Parsing Rules for libpod FilesfunctionsIDREF="chap632"Library Functions Listed by Purposelocal functionsIDREF="chap626"Standard and Local libpod Functionsstandard functionsIDREF="chap627"Standard and Local libpod Functionslibpod man pageIDREF="apenF33"Reference PageslibprintuiIDREF="chap188"Printing Application DevelopmentIDREF="chap114"OverviewIDREF="chap186"Printing Application DevelopmentIDREF="gloss22"GlossaryIDREF="chap53"OverviewIDREF="chap181"glp (PrintPanel)libprintui APIIDREF="chap169"libprintui APIlibprintui libraryIDREF="chap172"libprintui APIIDREF="chap68"The libprintui LibrarycompilingIDREF="chap611"Compiling Programs With libprintuiexample programIDREF="chap616"Example ProgramfunctionsIDREF="chap612"Library Functions Listed by Purposelibprintui man pageIDREF="apenF35"Reference PageslibrarylibimpIDREF="chap128"OverviewlibpodIDREF="chap118"OverviewlibprintuiIDREF="chap115"OverviewIDREF="chap171"libprintui APIlibscanIDREF="chap122"OverviewlibspoolIDREF="chap126"OverviewIDREF="chap129"OverviewIDREF="intro14"About This GuideIDREF="chap113"OverviewIDREF="chap123"OverviewIDREF="chap116"OverviewIDREF="chap119"OverviewlibstiffIDREF="chap125"OverviewlibscanIDREF="chap193"Complying With the Impressario Scanning ArchitectureIDREF="chap121"OverviewIDREF="gloss23"Glossarylibscan man pageIDREF="apenF42"Reference Pageslibscan.aIDREF="chap192"Complying With the Impressario Scanning ArchitectureIDREF="apenE2"OverviewlibspoolIDREF="intro15"About This GuideIDREF="chap168"libspool APIIDREF="chap112"OverviewIDREF="gloss24"GlossaryIDREF="chap184"Printing Application DevelopmentIDREF="chap185"Printing Application DevelopmentIDREF="chap187"Printing Application DevelopmentIDREF="chap177"libpod APIlibspool APIIDREF="chap166"libspool APIlibspool libraryIDREF="chap62"The libspool LibrarycompilingIDREF="chap65"Compiling Programs With libspoolfunctionsIDREF="chap66"libspool Library Functionslibspool man pageIDREF="apenF31"Reference PageslibstiffIDREF="chap124"OverviewIDREF="apenF45"Reference PagesIDREF="apenA4"Stream TIFF Data FormatIDREF="gloss25"Glossarylibstiff man pageIDREF="apenF44"Reference PagesIDREF="apenF37"Reference Pages.logIDREF="gloss42"GlossaryLocation CodeIDREF="apenC38"Location Codelp commandIDREF="chap159"Printing Application Programming InterfacesIDREF="gloss26"Glossarylpr commandIDREF="gloss27"GlossaryIDREF="chap157"Printing Application Programming Interfaceslpschedcommand-line argumentsIDREF="chap42"Command-Line Argumentslpsched commandIDREF="gloss28"Glossarymaking a software distributionIDREF="chap112"Making a tar Archive for Software Distributionman pagefileconvertIDREF="apenF19"Reference PagesglpIDREF="apenF5"Reference PagesgrelnotesIDREF="intro3"About This GuidegscanIDREF="apenF15"Reference PagesImpressarioIDREF="apenF3"Reference PagesinstallfoliofontsIDREF="apenF25"Reference PagesinstallpcfontsIDREF="apenF27"Reference PageslibimpIDREF="apenF40"Reference PagesIDREF="apenF47"Reference PageslibpodIDREF="apenF34"Reference PageslibprintuiIDREF="apenF36"Reference PageslibscanIDREF="apenF43"Reference PageslibspoolIDREF="apenF32"Reference PageslibstiffIDREF="apenF38"Reference PagesprintersIDREF="apenF29"Reference PagesprintpanelIDREF="apenF9"Reference PagesIDREF="apenF7"Reference PagesprintstatusIDREF="apenF13"Reference PagesIDREF="apenF11"Reference PagespsripIDREF="apenF23"Reference PagesscannersIDREF="apenF17"Reference PagesvstiffIDREF="apenF21"Reference PagesManual Capable optionIDREF="apenC39"Manual Capablemanual pageIDREF="chap119"Packaging Impressario Printing SoftwareMaximum Addr optionIDREF="apenC41"Maximum AddrMaximum Print Area optionIDREF="apenC43"Maximum Print AreaMedia SizeIDREF="apenC86"Media SizeMedia Standard optionIDREF="apenC45"Media StandardMedia TypeIDREF="apenC88"Media TypeMedia Type optionIDREF="apenC47"Media TypeMedia Wait optionIDREF="apenC49"Media WaitMediaWaitTimeoutIDREF="chap321"Reserved OptionsIDREF="chap320"Reserved OptionsMinimum Addr optionIDREF="apenC51"Minimum AddrMinimum Print Area optionIDREF="apenC53"Minimum Print Areamodel fileIDREF="chap114"Packaging Impressario Printing SoftwareIDREF="chap41"Printer Model Filesbanner pagesIDREF="chap438"Printer-Specific Banner Pagecommand-line argumentsIDREF="chap43"Command-Line Argumentsdebug routinesIDREF="chap436"Debug Routinedevice interfaceIDREF="chap417"Device Interfacefiltering optionsIDREF="chap440"Printer-Specific Filtering Optionsgeneral optionsIDREF="chap412"Printer-Specific Optionsprinter nameIDREF="chap415"Printer NametemplateIDREF="chap413"Developer-Supplied Model File AdditionsMonoPostScriptIDREF="chap429"Printer TypeNumber of ColorsIDREF="apenC90"Number of ColorsNumber of Colors optionIDREF="apenC55"Number of Colorsonline man pagesIDREF="intro47"Online Reference PagesOpenScanner functionIDREF="chap87"Scanner Driver's PerspectiveIDREF="chap716"OpenScanner() FunctionOperational StatusIDREF="apenC84"Operational StatusOSF/MotifIDREF="chap58"Graphical Options Panel Developmentoutput-specific optionsIDREF="chap322"Reserved Optionsoverview of chapters and appendicesIDREF="intro42"Document Overviewpackaging Impressario printing softwareIDREF="chap113"Packaging Impressario Printing Softwarepackaging Impressario scanning softwareIDREF="chap1110"Packaging Impressario Scanning Softwarepackaging your Impressario productIDREF="chap111"Packaging Your Impressario Productpacked data formatIDREF="gloss29"GlossaryPCDIDREF="gloss31"GlossaryPDpod_path global variableIDREF="chap625"POD FilesphandlerIDREF="chap34"Printer Driver ExamplesPhysical LocationIDREF="apenC58"Physical Locationplanar data formatIDREF="gloss30"GlossaryPlotterIDREF="chap431"Printer TypeHP DesignJet 750CIDREF="intro18"New Featuresplotter formatIDREF="gloss32"Glossaryplp.hIDREF="chap37"Printer Driver ExamplesPODIDREF="gloss33"Glossarygeneral syntaxIDREF="apenC5"General SyntaxPOD filesIDREF="chap138"Step 2: Provide POD Files (Required)IDREF="chap116"Packaging Impressario Printing SoftwarePOD general syntaxIDREF="apenC6"General Syntaxcharacter setIDREF="apenC7"Character Setfield formatIDREF="apenC8"Field Formatpod.hIDREF="chap36"Printer Driver ExamplespoddIDREF="chap176"libpod APIPort PathIDREF="apenC60"Port PathPostScriptcolor and monoIDREF="chap428"Printer TypePostScript filesIDREF="intro8"About This GuidePostScript printerIDREF="gloss34"GlossaryPPMIDREF="gloss35"Glossaryprint clientIDREF="gloss36"GlossaryIDREF="chap629"Standard and Local libpod Functionsprint serverIDREF="chap628"Standard and Local libpod FunctionsIDREF="gloss37"GlossaryPrintBoxIDREF="gloss38"GlossaryIDREF="chap52"OverviewIDREF="chap180"glp (PrintPanel)example configurationsIDREF="chap69"Example Widget Configurationsman pageIDREF="chap633"Library Functions Listed by PurposeIDREF="chap613"Library Functions Listed by PurposePrintBox graphical interfaceIDREF="chap19"Overviewprintbox programIDREF="chap615"Example ProgramPrintBox widgetIDREF="intro9"About This Guideprinted booksIDREF="intro45"Online BooksprinterApple LaserWriter IIIDREF="chap217"Printer SupportApple LaserWriter IIfIDREF="chap220"Printer SupportApple LaserWriter IIgIDREF="chap221"Printer SupportApple LaserWriter IINTIDREF="chap218"Printer SupportApple LaserWriter IINTXIDREF="chap219"Printer SupportApple LaserWriter PlusIDREF="chap216"Printer Supportconvenience functionsIDREF="chap49"Defining Convenience FunctionsHewlett-Packard DesignJet 650CIDREF="chap222"Printer SupportHewlett-Packard DeskJet 500CIDREF="chap223"Printer SupportIDREF="chap226"Printer SupportHewlett-Packard DeskJet 550CIDREF="chap227"Printer SupportIDREF="chap224"Printer SupportHewlett-Packard LaserJet 4IDREF="chap229"Printer SupportHewlett-Packard LaserJet IIIIDREF="chap232"Printer SupportHewlett-Packard LaserJet IIIPIDREF="chap233"Printer SupportHewlett-Packard LaserJet IIPIDREF="chap230"Printer SupportHewlett-Packard LaserJet IIP+IDREF="chap231"Printer SupportHewlett-Packard PaintJet XL300IDREF="chap225"Printer SupportIDREF="chap228"Printer SupportHP DeskJet 1600CIDREF="intro22"New FeaturesHP DeskJet 660CIDREF="intro19"New FeaturesHP DeskJet 850CIDREF="intro20"New FeaturesHP DeskJet 855CIDREF="intro21"New FeaturesHP LaserJet 4 PlusIDREF="intro24"New FeaturesHP LaserJet 4SiIDREF="intro25"New FeaturesHP LaserJet 4VIDREF="intro23"New FeaturesHP LaserJet 5LIDREF="intro26"New FeaturesHP LaserJet 5PIDREF="intro27"New FeaturesHP LaserJet 5SiIDREF="intro28"New FeaturesnameIDREF="chap414"Printer Nameprocess command-line argumentsIDREF="chap410"Processing Command-Line ArgumentstypesIDREF="chap424"Printer TypePrinter ClassIDREF="apenC62"Printer Classprinter configurationIDREF="chap241"Printer Configurationprinter configuration fileIDREF="chap621"POD FilesIDREF="apenC2"Printer Configuration FileformatIDREF="apenC12"Printer Configuration File FormatparsingIDREF="apenC10"Input Parsing Rules for libpod Filesprinter driversdevelopmentIDREF="chap31"Printer Driversengine-specific optionsIDREF="chap318"Reserved OptionsexampleIDREF="chap33"Printer Driver Examplesinclude filesIDREF="chap38"Printer Driver ExamplesinvocationIDREF="chap39"Program Invocationoutput-specific optionsIDREF="chap323"Reserved Optionsraster-specific optionsIDREF="chap316"Reserved Optionsrequired optionsIDREF="chap314"Required Optionsrequired switchesIDREF="chap313"Required Optionsreserved optionsIDREF="chap315"Reserved Optionsunreserved optionsIDREF="chap325"Unreserved Optionsprinter log fileIDREF="apenC4"Printer Log FileIDREF="chap140"Step 2: Provide POD Files (Required)Printer ManagerIDREF="gloss39"GlossaryIDREF="chap427"Printer TypeIDREF="chap242"Printer ConfigurationPrinter ModelIDREF="apenC64"Printer Modelprinter model fileIDREF="gloss40"Glossaryprinter object databaseIDREF="gloss44"GlossaryIDREF="chap120"OverviewfilesIDREF="chap620"POD Filesprinter object database (POD) file formatsIDREF="apenC1"Printer Object Database (POD) File FormatsPrinter OptionsIDREF="apenC66"Printer OptionsIDREF="apenC92"Printer Optionsprinter status fileIDREF="chap141"Step 2: Provide POD Files (Required)IDREF="apenC3"Printer Status FileIDREF="chap623"POD FilesentriesIDREF="apenC82"Printer Status File EntriesformatIDREF="apenC101"Printer Log File FormatIDREF="apenC80"Printer Status File Formatgeneral formatIDREF="apenC81"General FormatparsingIDREF="apenC9"Input Parsing Rules for libpod Filesprinter status file entryErrorIDREF="apenC95"Error, Warning, and Information OptionsInformation OptionsIDREF="apenC97"Error, Warning, and Information OptionsMedia SizeIDREF="apenC85"Media SizeMedia TypeIDREF="apenC87"Media TypeNumber of ColorsIDREF="apenC89"Number of ColorsOperational StatusIDREF="apenC83"Operational StatusPrinter OptionsIDREF="apenC91"Printer OptionsValidation MaskIDREF="apenC93"Validation MaskWarningIDREF="apenC96"Error, Warning, and Information Optionsprinter status file formatIDREF="apenC79"Printer Status File Formatprinter supportIDREF="chap215"Printer Supportprinter-specific filter/driverIDREF="chap434"Printer-Specific Filter/DriverprintersIDREF="gloss45"Glossaryprinters graphical interfaceIDREF="chap13"Overviewprinters man pageIDREF="apenF28"Reference PagesPrintID functionIDREF="chap728"PrintID() Functionprinting application developmentIDREF="chap182"Printing Application Developmentprinting developers man pagesIDREF="apenF30"Reference Pagesprinting environmentIDREF="intro4"About This Guideprinting librariesIDREF="chap61"Printing Librariesprinting-specific STIFFIDREF="apenA12"Printing-Specific STIFFPrintPanelIDREF="chap179"glp (PrintPanel)IDREF="gloss46"Glossaryprintpanel man pageIDREF="apenF8"Reference PagesIDREF="apenF6"Reference PagesPrintStatusIDREF="gloss47"Glossaryprintstatus man pageIDREF="apenF12"Reference PagesIDREF="apenF10"Reference Pagesproviding data filtersIDREF="chap148"Step 4: Provide Data Filters (As Needed)providing POD filesIDREF="chap137"Step 2: Provide POD Files (Required)psrip man pageIDREF="apenF22"Reference PagesQuality Modes optionIDREF="apenC67"Quality Modesqueues and multi-threaded scanner driversIDREF="apenE82"Queues and Multi-Threaded Scanner Driversqueues manipulating functionsIDREF="apenE84"Queue Manipulating FunctionsRasterIDREF="chap433"Printer Typeraster printerIDREF="gloss48"Glossaryraster-specific optionsIDREF="chap317"Reserved Optionsrelated publicationsIDREF="intro43"Related Publicationsonline man pagesIDREF="intro46"Online Reference Pagesprinted booksIDREF="intro44"Online Booksremote interfacesIDREF="chap422"Device Interfacerequired scanner functionsIDREF="apenE6"Required Scanner FunctionsResolution optionIDREF="apenC69"ResolutionrouteprintIDREF="chap426"Printer Typeruntime filetype recognition utilityIDREF="chap125"Runtime File Type Recognition UtilitySCAbort functionIDREF="chap959"SCAbort() Functionscanconv.hIDREF="chap711"Header Filesscandrv.hIDREF="chap79"Header FilesSCANINFO data structureIDREF="chap712"SCANINFO Data Structurescanipc.hIDREF="chap710"Header FilesScannercoordinate systemIDREF="chap92"Coordinate System for Scanningdata structuresIDREF="chap75"Header Filesdata type conventionsIDREF="chap94"Data Type Conventionsdriver templateIDREF="chap73"Header FilesdriversIDREF="chap71"Scanner DriversEpson GT 6000IDREF="chap239"Scanner Supportheader filesIDREF="chap77"Header FilesHewlett-Packard ScanJet IIcIDREF="chap235"Scanner Supportinstallation and testingIDREF="chap737"InstallationMicroTek ScanMaker 600 ZSIDREF="chap237"Scanner SupportRicoh FS1IDREF="chap236"Scanner SupportSharp JX 320IDREF="chap238"Scanner Supportscanner configurationIDREF="chap243"Scanner Configurationscanner data typemonochromeIDREF="chap95"Data Type Conventionspacked 24-bit RGB colorIDREF="chap97"Data Type Conventionsplanar 24-bit RGB colorIDREF="chap96"Data Type Conventionsscanner diagnostic functionsIDREF="chap98"Diagnostic Functionsscanner driver architectureIDREF="apenE83"Queues and Multi-Threaded Scanner DriversIDREF="apenE1"Scanner Driver Architecturescanner driver interfaceIDREF="chap83"Options Program and the Scanner Driver Interfacescanner driver interface options programIDREF="chap84"Options Program and the Scanner Driver Interfacescanner driver structureIDREF="apenE4"Driver Structurescanner driversIDREF="gloss49"Glossaryscanner functionsIDREF="apenE5"Scanner FunctionsrequiredIDREF="apenE7"Required Scanner Functionsscanner supportIDREF="chap234"Scanner Supportscanner-specific optionsIDREF="chap81"Scanner-Specific Optionsscanner-specific options programIDREF="chap88"Options Program's Perspectivescanner.hIDREF="chap78"Header FilesscannersIDREF="chap815"Installation and TestingIDREF="gloss50"Glossaryscanners man pageIDREF="apenF16"Reference Pagesscanning area functionsIDREF="chap939"Scanning Area Functionsscanning developers reference pagesIDREF="apenF41"Reference Pagesscanning environmentIDREF="intro13"About This Guidescanning functionsIDREF="chap944"Scanning Functionsscanning resolution functionsIDREF="chap934"Scanning Resolution FunctionsSCANPARAMS data structureIDREF="chap714"SCANPARAMS Data StructureSCBandRGB8ToPixelRGB8 functionIDREF="apenE76"SCBandRGB8ToPixelRGB8() FunctionSCClose functionIDREF="chap920"SCClose() FunctionSCCreateQueue functionIDREF="apenE85"Queue Manipulating FunctionsIDREF="apenE95"SCCreateQueue() FunctionSCCreateZoomMap functionIDREF="apenE58"SCCreateZoomMap() FunctionSCDataReady functionIDREF="chap953"SCDataReady() FunctionSCDATATYPE data structureIDREF="chap93"SCDATATYPE Data StructureSCDefaultScannerName functionIDREF="chap932"SCDefaultScannerName() FunctionSCDequeue FunctionIDREF="apenE91"Queue Manipulating FunctionsIDREF="apenE104"SCDequeue() FunctionSCDestroyQueue FunctionIDREF="apenE87"Queue Manipulating FunctionsIDREF="apenE98"SCDestroyQueue() FunctionSCDestroyZoomMap functionIDREF="apenE61"SCDestroyZoomMap() FunctionSCEndScanEnt functionIDREF="chap926"SCEndScanEnt() FunctionSCEnqueue FunctionIDREF="apenE90"Queue Manipulating FunctionsIDREF="apenE102"SCEnqueue() FunctionIDREF="apenE103"SCEnqueue() FunctionSCErrorString functionIDREF="chap911"SCErrorString() FunctionSCFeederAdvance functionIDREF="chap970"SCFeederAdvance() FunctionSCFeederGetFlags functionIDREF="chap966"SCFeederGetFlags() FunctionSCFeederReady functionIDREF="chap972"SCFeederReady() FunctionSCFeederSetFlags functionIDREF="chap968"SCFeederSetFlags() FunctionSCGetDataTypes functionIDREF="chap942"SCGetDataTypes() FunctionSCGetFD functionIDREF="chap955"SCGetFD() FunctionSCGetMinMaxRes functionIDREF="chap937"SCGetMinMaxRes() FunctionSCGetPageSize functionIDREF="chap940"SCGetPageSize() FunctionSCGetScanEnt functionIDREF="chap924"SCGetScanEnt() FunctionSCGetScanLine functionIDREF="chap951"SCGetScanLine() FunctionSCGetScannerRes functionIDREF="chap935"SCGetScannerRes() FunctionSCGetScanOptIDREF="chap813"Options Program's PerspectiveIDREF="chap810"Options Program's PerspectiveSCGetScanSize functionIDREF="chap947"SCGetScanSize() FunctionSCGetStatus functionIDREF="chap961"SCGetStatus() FunctionSCGetStatusFD functionIDREF="chap963"SCGetStatusFD() FunctionSCGrey8ToMono functionIDREF="apenE79"SCGrey8ToMono() FunctionSCLOPT structureIDREF="chap86"Options Program and the Scanner Driver Interfacesclopt.hIDREF="chap85"Options Program and the Scanner Driver InterfaceSCN_ABORT functionIDREF="apenE50"SCN_ABORT() FunctionSCN_DIE functionIDREF="apenE53"SCN_DIE() FunctionSCN_FEEDERADVANCEIDREF="apenE40"SCN_FEEDERADVANCE() FunctionSCN_FEEDERADVANCE functionIDREF="apenE38"SCN_FEEDERADVANCE() FunctionSCN_FEEDERGETFLAGS functionIDREF="apenE29"SCN_FEEDERGETFLAGS() FunctionSCN_FEEDERREADY functionIDREF="apenE35"SCN_FEEDERREADY() FunctionSCN_FEEDERSETFLAGS functionIDREF="apenE32"SCN_FEEDERSETFLAGS() FunctionSCN_GETSIZE functionIDREF="apenE44"SCN_GETSIZE() FunctionSCN_INITOK FunctionIDREF="apenE8"SCN_INITOK() FunctionSCN_MINMAXRES functionIDREF="apenE14"SCN_MINMAXRES() FunctionSCN_NRES functionIDREF="apenE17"SCN_NRES() FunctionSCN_NTYPES functionIDREF="apenE23"SCN_NTYPES() FunctionSCN_PAGESIZE functionIDREF="apenE11"SCN_PAGESIZE() FunctionSCN_RES functionIDREF="apenE20"SCN_RES() FunctionSCN_SCAN functionIDREF="apenE47"SCN_SCAN() FunctionSCN_SETUP functionIDREF="apenE41"SCN_SETUP() FunctionSCN_TYPES functionIDREF="apenE26"SCN_TYPES() FunctionSCOpenIDREF="apenE3"OverviewSCOpen functionIDREF="chap914"SCOpen() FunctionSCOpenFile functionIDREF="chap918"SCOpenFile() FunctionSCOpenScreen functionIDREF="chap916"SCOpenScreen() FunctionSCOptionsIDREF="chap89"Options Program's PerspectiveSCPerror functionIDREF="chap99"SCPerror() FunctionSCQueueSetExit functionIDREF="apenE107"SCQueueSetExit() FunctionIDREF="apenE93"Queue Manipulating FunctionsSCScan functionIDREF="chap949"SCScan() FunctionSCScanFD functionIDREF="chap957"SCScanFD() FunctionSCScannerName functionIDREF="chap928"SCScannerName() FunctionIDREF="chap930"SCScannerEnt() FunctionSCScanOptIDREF="chap814"Options Program's PerspectiveSCSetScanEnt functionIDREF="chap922"SCSetScanEnt() FunctionSCSetup functionIDREF="chap945"SCSetup() FunctionSCZoomRow1 functionIDREF="apenE64"SCZoomRow1() FunctionSCZoomRow24 functionIDREF="apenE70"SCZoomRow24() FunctionSCZoomRow32 functionIDREF="apenE73"SCZoomRow32() FunctionSCZoomRow8 functionIDREF="apenE67"SCZoomRow8() Functionserial interfacesIDREF="chap420"Device Interfaceserver softwareIDREF="intro12"About This GuideSetFeederFlags functionIDREF="chap722"SetFeederFlags() FunctionSetupScan functionIDREF="chap718"SetupScan() FunctionSGIIDREF="gloss51"GlossarySilicon Graphics filter/driver specificationIDREF="chap311"The Filter/Driver Specification and psripSilicon Graphics Image file format APIIDREF="apenB1"Silicon Graphics Image File Format APISilicon Graphics Image filesIDREF="intro7"About This GuideSize Table Entry optionIDREF="apenC71"Size Table Entryspooling system APIIDREF="gloss52"GlossaryIDREF="chap64"The libspool Library.statusIDREF="gloss43"Glossarystatus fileIDREF="chap624"POD FilesStatus Update WaitIDREF="apenC74"Status Update WaitSTIFFIDREF="gloss53"GlossarySTIFF data formatIDREF="apenA2"Stream TIFF Data FormatSTIFF generic functionsIDREF="apenA9"Library FunctionsSTIFF library accessIDREF="apenA7"Library AccessSTIFF library descriptionIDREF="apenB2"Library DescriptionIDREF="apenA6"Library DescriptionSTIFF library functionsIDREF="apenA8"Library FunctionsSTIFF printing-specific functionsIDREF="apenA10"Library Functionsstream TIFFIDREF="apenA3"Stream TIFF Data Formatstyle conventionsIDREF="intro30"Conventions Used in This GuidenotationsIDREF="intro31"Conventions Used in This GuidesyntaxIDREF="intro32"Conventions Used in This Guidesummary of libpod functionsIDREF="chap614"Library Functions Listed by PurposeIDREF="chap67"libspool Library FunctionsIDREF="chap634"Library Functions Listed by PurposeIDREF="chap25"Impressario Productssyntax conventionboldIDREF="intro36"Conventions Used in This GuidecourierIDREF="intro38"Conventions Used in This GuideIDREF="intro40"Conventions Used in This GuideitalicsIDREF="intro34"Conventions Used in This GuideSystem V spooler interfaceIDREF="chap158"Printing Application Programming InterfacesIDREF="gloss54"GlossaryTagged Image File FormatIDREF="gloss55"GlossaryTechnologyIDREF="apenC76"Technologytemplate model file executionIDREF="chap48"Template Model File ExecutiontesticonfigIDREF="chap106"Testing an Impressario Printer Software InstallationIDREF="chap152"Step 7: Verify Product on Server (Required)testing an Impressario printerIDREF="chap103"Testing an Impressario Printertesting an Impressario printer software installationIDREF="chap105"Testing an Impressario Printer Software InstallationtestiprIDREF="chap104"Testing an Impressario PrinterIDREF="chap151"Step 7: Verify Product on Server (Required)TIFFIDREF="gloss56"GlossaryTime per Page optionIDREF="apenC77"Time per Pageunreserved optionsIDREF="chap324"Unreserved Optionsuser nameIDREF="chap45"Command-Line Argumentsusing an alternate PostScript RIPIDREF="chap1214"Using an Alternate PostScript RIPValidation MaskIDREF="apenC94"Validation MaskVersatec interfacesIDREF="chap423"Device Interfacevstiff man pageIDREF="apenF20"Reference PagesWarningIDREF="apenC99"Error, Warning, and Information Optionswidgetexample configurationsIDREF="chap610"Example Widget Configurationswriting a new filterIDREF="chap1211"Writing a New Filterwriting an FTRIDREF="chap1212"Writing an FTRwstype utilityIDREF="chap126"Runtime File Type Recognition UtilityX and Xt Motif documentation setIDREF="chap811"Options Program's PerspectiveX applicationsIDREF="chap617"Initial Program ProcessingXt optionsIDREF="chap514"Invocation by the PrintBox WidgetXtAppInitializeIDREF="chap812"Options Program's PerspectiveYMC data formatIDREF="gloss57"GlossaryIDREF="apenA15"Generic STIFF File StructureYMCK data formatIDREF="apenA16"Generic STIFF File StructureIDREF="gloss58"Glossaryzooming and type conversion functionsIDREF="apenE56"Zooming and Type Conversion FunctionsIDREF="apenE57"Zooming and Type Conversion Functionszooming FunctionsIDREF="apenB92"Zooming Functions
